Re: [Jython-dev] Jython 2.7.1 rc3 soft release

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

On Sat, Jun 24, 2017 at 2:33 AM, Jeff Allen <ja...@fa...> wrote:

> Improving our documentation and what is prominent on the website is a good
> idea. Explaining our work accurately in an obvious place will do a lot for
> its usefulness to others and ease contribution.
>
> For example, as I created the simple Eclipse project to answer
> https://github.com/jythontools/jython/issues/78, a user struggling simply
> to get started, I thought that it ought to be on the wiki or somewhere. And
> we never pitched in with Frank's conversion of the Python documentation
> that describes with apparent authority things Jython doesn't do at all.
>
> +1 for using a Github repo. Also, a separate one for a dev guide. The
> CPython dev-guide was the first to migrate, wasn't it?


Indeed, the Jython dev guide currently can be found here:
https://hg.python.org/jython-docs/devguide/ - it should be moved over to
GitHub. Given history from CPython before it was forked, and the chance to
merge forward some of their updates, it's probably best to keep as a
separate repo.


> If we have those two on Github, can we give up the Wiki?
>

+1, no more wiki. We move the content over, and kill. The PR process is
just about as light, and it doesn't have the current problems in the wiki.


> I'd like to help with this, but in the immediate future I'm committed to
> other things -- not for an entire summer of code, you understand, but for
> the next three weeks at least.


It's not a problem! We always have varying availability, especially with
this project. But this flexibility is why I personally can find it easy to
continue to contribute, as I have time.


> So I can only recommend for 1/7 doing things that are least work, like
> linking the CPython 2.7 docs with an appropriate caveat. At least that
> sends a good message about conformance!
>

Any process should be about a simple workflow that's easy to contribute to.
We can then make it better.


> Longer term, I wonder if we can have a kind of filtered re-use, parallel
> to the way we treat the standard library? And the same with the dev guide?
>

Sounds like the right approach. There might be a way to be more systematic
here in how we patch, but the stdlib experience is reasonably light and
easy to work with.


>
> As for tools,  I've used the Maven Sphinx plug-in successfully (and it's
> nice that it depends on Jython).


Interesting detail! Might be the right approach in the future, depending on
our CI system.


> Also using CPython & Sphinx, I have published successfully through
> readthedocs.


I have had decent experience with RTD as well.


> I tried Github pages with Sphinx, but it ended up a mess: ISTR one is
> committing material generated from one branch into an alternate branch.
> Maybe it has got slicker, or maybe I was doing it wrong. Still, it makes me
> a bit wary about diving down that route (and requesting "PSF admins update
> DNS to point jython.org <http://jython.org> accordingly") rather than
> just linking it from an old-school home page where it is now.
>

I see jython.github.io as just one possible way to render static content,
that is then built by some other tooling against the doc repo, but the more
important thing is just using Sphinx + RST. Everything else in this
rendering pipeline we can readily change.


> ANTLR & StringTemplate just have documentation in the repo that Github
> renders directly, but I found Github markdown insufficient when I tried it
> for each of the jobs I refer to.
>

This is the most common approach, and works for many projects, but given
that RST is the standard for Python docs itself, plus used by the Jython
book, we should stick to RST.

In my other work, I generally prefer Markdown otherwise, especially given
its superior Github browsing integration. I also like being able to readily
embed Latex into Markdown using Pandoc tools, but a separate conversation
altogether. Anyway, it's not possible to have everything!


> I don't know the Travis plug-in. One needs to be able to generate the
> documentation locally, of course. If Travis does so much for us, will we be
> able to check work without opening a PR?
>

Regardless it should still be possible to build without a PR or the CI
itself, just by invoking Sphinx.

Having it on the PR (if possible, RTD doesn't currently support,
https://github.com/rtfd/readthedocs.org/issues/1340) will it make possible
to view changes without having to do this local checkout, which is nicer
workflow IMHO for initial review. So that's the biggest argument for Travis
I think at this time. But first, let's see if it's even workable, and if
not, we can just use RTD.

- Jim