Re: [Jython-dev] A new Jython DevGuide

[Jim B. <jim...@py...>]

Some top posting first:

We should just use read the docs; and point our CNAME for jython.org (and
related domains) to it (
http://docs.readthedocs.io/en/latest/alternate_domains.html). Currently
there are too many bottlenecks to getting stuff done in Jython, and that's
super frustrating. Automation can resolve some of these bottlenecks. Also I
don't want to be one of the bottlenecks myself!!! Did I say I wanted to
work on docs earlier this summer? I did work a bit on it privately, but
then it got buried under my general pile of stuff. This should not be
stopping anyone else working on this issue however.

Anyway...

I have an existing RTD project, https://readthedocs.org/projects/jython/
Rather than having it point to the Jython book, it might make more sense to
have be the overall project or at least to https://github.com/jython/docs
(not there yet!). See subproject support:
http://docs.readthedocs.io/en/latest/subprojects.html

Jeff, and others here, I can add you to the jython project on RTD as
admins. Just need your username.

There may be better approaches, but nothing is as simple as RTD given the
source is reStructuredText. Also IIRC, RTD does allow some degree of
customization of the look, although I personally would be so much happier
with fresh and current content, vs any customization!


On Mon, Oct 23, 2017 at 1:40 AM, Jeff Allen <ja...@fa...> wrote:

> I've finished my preliminary restructuring of the developers' guide at
> https://github.com/jython/devguide.
>
+1

> You'll recall that one of the prompts for this was lessening support for
> hg.python.org. We want to follow CPython and get the Jython source over
> to GitHub. For that we need a changed core development and contribution
> process, like CPython's, where everyone can read it. So far, I have:
>
>    1. Stolen CPython's text and structure.
>    2. Assessed which pages work for us unchanged or with only minor
>    change.
>    3. Made parallel pages (name_jy.rst) where the content differs widely.
>    4. Integrated Frank's Jython-specific text from the current devguide
>    into those and some unique pages.
>    5. Added a bit of content myself.
>    6. Contributed a few technical improvements upstream to the CPython
>    devguide.
>    7. Merged changes from the upstream CPython devguide (not just mine)
>    into the Jython devguide.
>
> The merge was not totally painless, but only 3 files gave me conflicts. It
> took a couple of hours with kdiff3, and working carefully from the Git
> Book. It's feasible, but there may be a better way. Two of these files had
> a lot of differences. Somehow kdiff3 seemed to guess correctly nearly
> everywhere.
>
Yay, tools! Given the scope of just the devguide, it's good to hear that it
worked so well.

> Could we think about how we publish this so it becomes a functional
> replacement for http://www.jython.org/devguide ? It is not ready yet, but
> if we all think it will be, then the question becomes how. I could set up
> publishing to readthedocs (on my own account), but do we have a Jython/PSF
> one? Or is it better to take the html to jython.org as we have previously?
> It was nice to see my PRs to the CPython guide, once accepted, go live on
> docs.python.org within hours. I assume this happens automatically. That's
> to aim for, I think, creating one decision point (the PR acceptance) and
> giving the rest of the job to machines.
>

+100