Re: Where to add documentation details about jarray / registry?

Ha! I don't think I've ever looked in /Doc. Certainly not with any 
understanding. :/ I don't know how those files become anything on the 
website. The only reference I can find is in Misc/Release.py, also a 
living fossil.

Ok, https://jython.github.io/ is the nearest we have to a website right 
now (some problem getting it to jython.org). I thought maybe you'd found 
the source of https://jython.org/docs/index.html. I think something on 
the documentation menu next to Python 2.7 would be good, that talks 
about the differences from Python 2.7. Maybe the /Doc directory contains 
a start. Beware fossils. (jreload is gone.)

Jython wiki contains valuable information, but it feels a safe as Notre 
Dame tonight.

ant generates the javadoc. Or gradle.

Jeff

Jeff Allen

On 15/04/2019 09:08, Adam Burke wrote:
> 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 <http://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 <[email protected] 
> <mailto:[email protected]>> 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 <[email protected]
>>     <mailto:[email protected]>> 写道：
>>
>>>     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
>>>>

_______________________________________________
Jython-dev mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/jython-dev