Re: [Jython-dev] Where to add documentation details about jarray / registry?

[Adam B. <ada...@gm...>]

I was thinking of  https://github.com/jython/jython.github.io ... as the
"user docs in git".

I note now there is a top level folder in the main Jython project named
"Doc" though. It seems to have user-facing pages including one on jarray,
which corresponds to the one I linked earlier. Last commit ... 11 years ago.

Which documents do you mean by the developer docs?

So far I see

1/ User-facing: Git-maintained markdown, target website:
https://github.com/jython/jython.github.io

2/ Archived sites on jython.org

3/ Doc/ in jython source project

4/ Jython wiki

5/ Javadoc (not clear on when this is generated)

Sorry if I'm being thick.

Adam


On Mon, 15 Apr 2019 at 17:52, Jeff Allen <ja...@fa...> wrote:

> What exactly do you mean by "the new git docs"? I don't think we have
> Jython user docs in git, only developer docs. There's an old one in hg I
> think.
>
> The developer docs were a bit of an experiment. In the developer docs, the
> idea was to keep all the CPython content but create additional Jython
> pages, including a replacement start page. I kept the CPython pages so
> changes from upstream still update them. Some of the pages don't work at
> all for Jython, so are not in the main index, and are present so upstream
> change has somewhare to land. Others remain valid for Jython, or are valid
> with small modifications (to be merged with care).
>
> I don't know if we can inherit the CPython user docs in the same way, but
> I'm happy to see it tried. One needs to take the docs of the target version
> of CPython we are most like. It will take significant editing initially,
> but won't need much change while the target version is the same. Maybe
> there *is* no upstream change to speak of. When we advance that target
> version, what happens? My main critereon is that we don't create a thing we
> can't afford to maintain.
>
> Jeff
>
> Jeff Allen
>
> On 14/04/2019 02:57, Adam Burke wrote:
>
> > (isn't it neat!)
>
> Yes, and in a lovely jythonesque way : )
>
> On the docs, I guess I agree that you want to inherit the CPython docs,
> plus being able to note variations in Jython, plus some pages on
> Jython-specific elements. This might just be a separate index to module
> documentation, say for jarray, or it might be specific language features,
> like Java imports. (And a website to put it on, indeed.)
>
> If there is not a specific target area already for Jython specific
> features, I will send a doc patch carving out an area in the new git docs.
> This should not interfere much with any later work to synch with the
> CPython docs. I will probably copy some of the 2.1 archive material linked
> below.
>
> Cheers
> Adam
>
> 在 2019年4月14日，上午2:26，Jeff Allen <ja...@fa...> 写道：
>
> Thanks for responding on that. I didn't know the answer off the top of my
> head (isn't it neat!), but thought you, James or Stefan might. I was once
> told jarray was not much used, meaning en route to deprecation, but until
> there is a compatible ndarray ... .
>
> Ideally we whould have a set of documentation that is a copy of the
> CPython one with amendements. (And a web site to put it on.) But it's work.
> We might get away increasingly with referring to the CPython documents,
> because of increasing conformance to expectations created by CPython. It
> will never really reduce the need to zero, however. I don't know how
> affordably to maintain a large document that is only a little different
> from CPython's. I had a go with the dev-guide and think it saved work to
> borrow by forking, but it was still a fair amount of effort and not wholly
> successful in keeping up.
>
> Language and module documentation has a different balance, though.
>
> I think an approach that mimics CPython's structurally, but contains only
> notes about differences would work and a link to the CPython doc. It's a
> good reason to have a clearer answer to "what CPython are you most like"
> than we can normally give, since that's the version we would link. Where to
> put it though?
>
> Jeff Allen
>
> On 13/04/2019 12:53, Adam Burke wrote:
>
> There was a bug raised today which is already a feature, and really just
> points to a documentation gap. I made a comment there, and was going to add
> some doc, so went for the right place to enhance pages on the jarray
> module. Basically I was expecting to add a few lines to a page like this
> (which still turns up high on google)
>
> https://www.jython.org/archive/21/docs/jarray.html
>
> However it seems jython specific details like jarray or the jython
> registry might have been victims of multiple documentation moves over the
> years since v2.1. I started looking on the new jython doco git project and
> moved out from there. There doesn't appear to be anything on the wiki
> either.
>
> That all being what it is - can someone point me to either an existing
> place to add to this, or where would the right place to add *back* a page
> on jarray in the target documentation structure?
>
> Cheers
> Adam
>
>