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

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

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... 
> <mailto: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
>>>