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

[James M. <jam...@gm...>]

I agree with Jeff a section on the new website documenting the differences
between Jython and CPython would be really useful. It was something on my
todo list but never got started. I think adding some new pages should be
easy if anyone wants to try.

Or if we think there are docs worth converting I could probably find time
to do that. Should we open an issue on the website Github to track it?

James

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

> 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
>
> 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
>>
>> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev
>