Re: [Jython-dev] A new Jython DevGuide

[Jeff A. <ja...@fa...>]

Just playing this back to get it straight ... the idea would be to 
publish the devguide as a document at readthedocs (thanks for the 
access), and link it, and so much else, from a website that develops in 
this repo: https://github.com/jython/jython.github.io .

There are help pages about it, I know, but as a living example, it would 
be like the PyInstaller site where 
https://github.com/pyinstaller/pyinstaller.github.io is instantiated as 
http://www.pyinstaller.org/

This sounds good to me, and lets us share this kind of work more easily.

Jeff

Jeff Allen

On 23/10/2017 19:19, Jim Baker wrote:
> Some top posting first:
>
> We should just use read the docs; and point our CNAME for jython.org 
> <http://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... 
> <mailto:ja...@fa...>> wrote:
>
>     I've finished my preliminary restructuring of the developers'
>     guide at https://github.com/jython/devguide
>     <https://github.com/jython/devguide>.
>
> +1
>
>     You'll recall that one of the prompts for this was lessening
>     support for hg.python.org <http://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 <http://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 <http://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
>