jython-dev

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

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

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

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

[Jeff A. <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
>

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

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

> (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
>> 

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
>>>

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
>
>

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

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

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 <ja...@fa... 
> <mailto: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...
>>     <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
>>>>

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
>

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

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

On 16/04/2019 20:17, James Mudd wrote:
> 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.
>
> On Mon, 15 Apr 2019 at 21:41, Jeff Allen <ja...@fa... 
> <mailto: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.
>
FYI, I found a couple of scripts under Misc/htgen that look like they 
process th.ht files in ~/Doc. -- Jeff

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

[Stefan R. <ste...@gm...>]

By coincidence, while here this discussion about doc started, on the core
mentorship list someone brought up the idea the PSF should apply at
https://developers.google.com/season-of-docs/. Maybe we could contribute a
project suggestion to that discussion. They mainly have CPython in mind,
but the PSF served as an umbrella organization before in GSoC. This new
program seems to be organized in a similar way.

Best

-Stefan

Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd <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
>>
> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev
>

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

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

Hi all

April 23 (today my time) is actually the deadline for mentoring
organizations, which I think is us in the terminology google use.

https://developers.google.com/season-of-docs/docs/

Here is a draft proposal. I am not involved with the Python mentor
discussion but please feel free to throw it into the ring. Even if we
aren't selected (or even submitted in time) it can be useful for thinking
about what we want our docs to look like.

--
Proposal:

Jython is a well-established and stable pure Java implementation of the
Python interpreter. Over the life of the (15+ year old) project,
documentation has become fragmented and inconsistent. A new github and
markdown documentation project and corresponding website has been
established, but it still needs significant consolidation and reworking of
content from multiple high quality but out of date sources. (The new
project is https://github.com/jython/jython.github.io.) The documentation
could also benefit from the consistency and whole-project view of a
technical writer.

This project includes
  * Editing and reintegration of archived documentation from versions 2.1,
2.2 and 2.2.1. This is ht2html generated static HTML from HTML template
source in the jython source repository
  * Repairing the public version of the open soruce Jython book, and
incorporating links to other published Jython books and papers
  * Consolidating release notes from 2.2 - 2.7 in one consistent location
and format
  * Clarifying the focus of the Jython wiki and migrating more official
material from there to the main documentation project (or possibly
deprecating the wiki entirely)
  * Integrating Jython module documentation and having a clear navigation
and dependency mechanism where it extends or varies from Python libraries.
A strength of Jython is that a large proportion of Python libraries are
used unchanged; the documentation should reflect this in a way useful to
both users and Jython core developers.
  * Reviewing and proposing improvements to the structure of the main
documentation project itself

Stakeholders and mentors for this process would be the Jython core
development team as represented on the jython-dev mailing list,
particularly James Mudd and <X and Y***>.

--

*** It would be good to have an experienced core dev, but I am happy to be
involved and named

Cheers
Adam

On Wed, 17 Apr 2019 at 09:44, Stefan Richthofer <ste...@gm...>
wrote:

> By coincidence, while here this discussion about doc started, on the core
> mentorship list someone brought up the idea the PSF should apply at
> https://developers.google.com/season-of-docs/. Maybe we could contribute
> a project suggestion to that discussion. They mainly have CPython in mind,
> but the PSF served as an umbrella organization before in GSoC. This new
> program seems to be organized in a similar way.
>
> Best
>
> -Stefan
>
> Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd <
> 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
>>>
>> _______________________________________________
>> Jython-dev mailing list
>> Jyt...@li...
>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev
>

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

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

Thanks for this Adam

I think it would definitely be good to get someone to spend some actual
time sorting out the docs, and maybe this is a way to do it. Your
suggestion for the project outline looks good to me, I really think there
is lots of good stuff out there it just needs consolidating and updating.
I'm not on the mentors at the moment but could maybe help with this
project. My only concern is I am changing jobs at the start of June and not
sure how much time I can offer to help, but if there are a few others
available too then I think it could work.

James.

On Tue, 23 Apr 2019 at 11:57, Adam Burke <ada...@gm...> wrote:

> Hi all
>
> April 23 (today my time) is actually the deadline for mentoring
> organizations, which I think is us in the terminology google use.
>
> https://developers.google.com/season-of-docs/docs/
>
> Here is a draft proposal. I am not involved with the Python mentor
> discussion but please feel free to throw it into the ring. Even if we
> aren't selected (or even submitted in time) it can be useful for thinking
> about what we want our docs to look like.
>
> --
> Proposal:
>
> Jython is a well-established and stable pure Java implementation of the
> Python interpreter. Over the life of the (15+ year old) project,
> documentation has become fragmented and inconsistent. A new github and
> markdown documentation project and corresponding website has been
> established, but it still needs significant consolidation and reworking of
> content from multiple high quality but out of date sources. (The new
> project is https://github.com/jython/jython.github.io.) The documentation
> could also benefit from the consistency and whole-project view of a
> technical writer.
>
> This project includes
>   * Editing and reintegration of archived documentation from versions 2.1,
> 2.2 and 2.2.1. This is ht2html generated static HTML from HTML template
> source in the jython source repository
>   * Repairing the public version of the open soruce Jython book, and
> incorporating links to other published Jython books and papers
>   * Consolidating release notes from 2.2 - 2.7 in one consistent location
> and format
>   * Clarifying the focus of the Jython wiki and migrating more official
> material from there to the main documentation project (or possibly
> deprecating the wiki entirely)
>   * Integrating Jython module documentation and having a clear navigation
> and dependency mechanism where it extends or varies from Python libraries.
> A strength of Jython is that a large proportion of Python libraries are
> used unchanged; the documentation should reflect this in a way useful to
> both users and Jython core developers.
>   * Reviewing and proposing improvements to the structure of the main
> documentation project itself
>
> Stakeholders and mentors for this process would be the Jython core
> development team as represented on the jython-dev mailing list,
> particularly James Mudd and <X and Y***>.
>
> --
>
> *** It would be good to have an experienced core dev, but I am happy to be
> involved and named
>
> Cheers
> Adam
>
> On Wed, 17 Apr 2019 at 09:44, Stefan Richthofer <
> ste...@gm...> wrote:
>
>> By coincidence, while here this discussion about doc started, on the core
>> mentorship list someone brought up the idea the PSF should apply at
>> https://developers.google.com/season-of-docs/. Maybe we could contribute
>> a project suggestion to that discussion. They mainly have CPython in mind,
>> but the PSF served as an umbrella organization before in GSoC. This new
>> program seems to be organized in a similar way.
>>
>> Best
>>
>> -Stefan
>>
>> Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd <
>> 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
>>>>
>>> _______________________________________________
>>> Jython-dev mailing list
>>> Jyt...@li...
>>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>>
>> _______________________________________________
>> Jython-dev mailing list
>> Jyt...@li...
>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
>

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

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

Hi Adam:

It's a really well-written proposal. I would agree that well describes 
what needs doing.

It would be good to have an author of the Jython book as a mentor, 
especially if part of the work is to update it. (ISTR Frank once invited 
us to, so isn't precious about it.) That's the bit I'm least keen to 
embark on myself, but might be the plumb bit to a technical writer.

I'm not sure we can live up to this: 
https://developers.google.com/season-of-docs/docs/admin-mentor-responsibilities, 
not as just the Jython project. It all seems to assume a much larger 
organisation than we have. (As the PSF, sure, but ... .) I barely have 
the time to encourage people contributing code.

Jeff

Jeff Allen

On 23/04/2019 17:57, James Mudd wrote:
> Thanks for this Adam
>
> I think it would definitely be good to get someone to spend some 
> actual time sorting out the docs, and maybe this is a way to do it. 
> Your suggestion for the project outline looks good to me, I really 
> think there is lots of good stuff out there it just needs 
> consolidating and updating. I'm not on the mentors at the moment but 
> could maybe help with this project. My only concern is I am changing 
> jobs at the start of June and not sure how much time I can offer to 
> help, but if there are a few others available too then I think it 
> could work.
>
> James.
>
> On Tue, 23 Apr 2019 at 11:57, Adam Burke <ada...@gm... 
> <mailto:ada...@gm...>> wrote:
>
>     Hi all
>
>     April 23 (today my time) is actually the deadline for mentoring
>     organizations, which I think is us in the terminology google use.
>
>     https://developers.google.com/season-of-docs/docs/
>
>     Here is a draft proposal. I am not involved with the Python mentor
>     discussion but please feel free to throw it into the ring. Even if
>     we aren't selected (or even submitted in time) it can be useful
>     for thinking about what we want our docs to look like.
>
>     --
>     Proposal:
>
>     Jython is a well-established and stable pure Java implementation
>     of the Python interpreter. Over the life of the (15+ year old)
>     project, documentation has become fragmented and inconsistent. A
>     new github and markdown documentation project and corresponding
>     website has been established, but it still needs significant
>     consolidation and reworking of content from multiple high quality
>     but out of date sources. (The new project is
>     https://github.com/jython/jython.github.io.) The documentation
>     could also benefit from the consistency and whole-project view of
>     a technical writer.
>
>     This project includes
>       * Editing and reintegration of archived documentation from
>     versions 2.1, 2.2 and 2.2.1. This is ht2html generated static HTML
>     from HTML template source in the jython source repository
>       * Repairing the public version of the open soruce Jython book,
>     and incorporating links to other published Jython books and papers
>       * Consolidating release notes from 2.2 - 2.7 in one consistent
>     location and format
>       * Clarifying the focus of the Jython wiki and migrating more
>     official material from there to the main documentation project (or
>     possibly deprecating the wiki entirely)
>       * Integrating Jython module documentation and having a clear
>     navigation and dependency mechanism where it extends or varies
>     from Python libraries. A strength of Jython is that a large
>     proportion of Python libraries are used unchanged; the
>     documentation should reflect this in a way useful to both users
>     and Jython core developers.
>       * Reviewing and proposing improvements to the structure of the
>     main documentation project itself
>
>     Stakeholders and mentors for this process would be the Jython core
>     development team as represented on the jython-dev mailing list,
>     particularly James Mudd and <X and Y***>.
>
>     --
>
>     *** It would be good to have an experienced core dev, but I am
>     happy to be involved and named
>
>     Cheers
>     Adam
>
>     On Wed, 17 Apr 2019 at 09:44, Stefan Richthofer
>     <ste...@gm... <mailto:ste...@gm...>>
>     wrote:
>
>         By coincidence, while here this discussion about doc started,
>         on the core mentorship list someone brought up the idea the
>         PSF should apply at
>         https://developers.google.com/season-of-docs/. Maybe we could
>         contribute a project suggestion to that discussion. They
>         mainly have CPython in mind, but the PSF served as an umbrella
>         organization before in GSoC. This new program seems to be
>         organized in a similar way.
>
>         Best
>
>         -Stefan
>
>         Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd
>         <jam...@gm... <mailto: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... <mailto: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 <http://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
>>                 <ja...@fa... <mailto: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... <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
>>>>>
>                 _______________________________________________
>                 Jython-dev mailing list
>                 Jyt...@li...
>                 <mailto:Jyt...@li...>
>                 https://lists.sourceforge.net/lists/listinfo/jython-dev
>
>             _______________________________________________
>             Jython-dev mailing list
>             Jyt...@li...
>             <mailto:Jyt...@li...>
>             https://lists.sourceforge.net/lists/listinfo/jython-dev
>
>         _______________________________________________
>         Jython-dev mailing list
>         Jyt...@li...
>         <mailto:Jyt...@li...>
>         https://lists.sourceforge.net/lists/listinfo/jython-dev
>
>
>
> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev

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

[Stefan R. <ste...@gm...>]

So the application deadline is in half an hour, I suspect it is fairly
impossible to get this into shape in time.
Also, it looks like the application would have to be done by the
organization leader which would be Frank in our case
or who-ever in PSF case. Some links I just digged out:
https://discuss.python.org/t/will-python-apply-for-season-of-docs-and-allow-suborgs/1105/13
https://discuss.python.org/t/projects-under-psf-that-need-documentation-support/1501
https://numfocus.org/blog/numfocus-projects-to-apply-for-inaugural-google-season-of-docs

So, it kind of looks like PSF does not apply due to lack of projects and
mentors. NumPy & co applied under NumFocus
umbrella which is no option for us (?). It looks to me like the whole PSF
at GSoD idea failed a reasonable incubation
period this year. Maybe it would be best to achieve this project draft for
next GSoD and start to incubate things early,
also check out the option of Jython applying on its own (e.g. if PSF does
not apply for whatever reason).

Best

-Stefan

Am Di., 23. Apr. 2019 um 21:24 Uhr schrieb Jeff Allen <ja...@fa...>:

> Hi Adam:
>
> It's a really well-written proposal. I would agree that well describes
> what needs doing.
>
> It would be good to have an author of the Jython book as a mentor,
> especially if part of the work is to update it. (ISTR Frank once invited us
> to, so isn't precious about it.) That's the bit I'm least keen to embark on
> myself, but might be the plumb bit to a technical writer.
>
> I'm not sure we can live up to this:
> https://developers.google.com/season-of-docs/docs/admin-mentor-responsibilities,
> not as just the Jython project. It all seems to assume a much larger
> organisation than we have. (As the PSF, sure, but ... .) I barely have the
> time to encourage people contributing code.
>
> Jeff
>
> Jeff Allen
>
> On 23/04/2019 17:57, James Mudd wrote:
>
> Thanks for this Adam
>
> I think it would definitely be good to get someone to spend some actual
> time sorting out the docs, and maybe this is a way to do it. Your
> suggestion for the project outline looks good to me, I really think there
> is lots of good stuff out there it just needs consolidating and updating.
> I'm not on the mentors at the moment but could maybe help with this
> project. My only concern is I am changing jobs at the start of June and not
> sure how much time I can offer to help, but if there are a few others
> available too then I think it could work.
>
> James.
>
> On Tue, 23 Apr 2019 at 11:57, Adam Burke <ada...@gm...> wrote:
>
>> Hi all
>>
>> April 23 (today my time) is actually the deadline for mentoring
>> organizations, which I think is us in the terminology google use.
>>
>> https://developers.google.com/season-of-docs/docs/
>>
>> Here is a draft proposal. I am not involved with the Python mentor
>> discussion but please feel free to throw it into the ring. Even if we
>> aren't selected (or even submitted in time) it can be useful for thinking
>> about what we want our docs to look like.
>>
>> --
>> Proposal:
>>
>> Jython is a well-established and stable pure Java implementation of the
>> Python interpreter. Over the life of the (15+ year old) project,
>> documentation has become fragmented and inconsistent. A new github and
>> markdown documentation project and corresponding website has been
>> established, but it still needs significant consolidation and reworking of
>> content from multiple high quality but out of date sources. (The new
>> project is https://github.com/jython/jython.github.io.) The
>> documentation could also benefit from the consistency and whole-project
>> view of a technical writer.
>>
>> This project includes
>>   * Editing and reintegration of archived documentation from versions
>> 2.1, 2.2 and 2.2.1. This is ht2html generated static HTML from HTML
>> template source in the jython source repository
>>   * Repairing the public version of the open soruce Jython book, and
>> incorporating links to other published Jython books and papers
>>   * Consolidating release notes from 2.2 - 2.7 in one consistent location
>> and format
>>   * Clarifying the focus of the Jython wiki and migrating more official
>> material from there to the main documentation project (or possibly
>> deprecating the wiki entirely)
>>   * Integrating Jython module documentation and having a clear navigation
>> and dependency mechanism where it extends or varies from Python libraries.
>> A strength of Jython is that a large proportion of Python libraries are
>> used unchanged; the documentation should reflect this in a way useful to
>> both users and Jython core developers.
>>   * Reviewing and proposing improvements to the structure of the main
>> documentation project itself
>>
>> Stakeholders and mentors for this process would be the Jython core
>> development team as represented on the jython-dev mailing list,
>> particularly James Mudd and <X and Y***>.
>>
>> --
>>
>> *** It would be good to have an experienced core dev, but I am happy to
>> be involved and named
>>
>> Cheers
>> Adam
>>
>> On Wed, 17 Apr 2019 at 09:44, Stefan Richthofer <
>> ste...@gm...> wrote:
>>
>>> By coincidence, while here this discussion about doc started, on the
>>> core mentorship list someone brought up the idea the PSF should apply at
>>> https://developers.google.com/season-of-docs/. Maybe we could
>>> contribute a project suggestion to that discussion. They mainly have
>>> CPython in mind, but the PSF served as an umbrella organization before in
>>> GSoC. This new program seems to be organized in a similar way.
>>>
>>> Best
>>>
>>> -Stefan
>>>
>>> Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd <
>>> 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
>>>>>
>>>> _______________________________________________
>>>> Jython-dev mailing list
>>>> Jyt...@li...
>>>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>>>
>>> _______________________________________________
>>> Jython-dev mailing list
>>> Jyt...@li...
>>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>>
>>
>
> _______________________________________________
> Jython-dev mailing lis...@li...https://lists.sourceforge.net/lists/listinfo/jython-dev
>
> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev
>

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

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

Have been surveying the current doco, widely if not deeply, and it seems to
me the most complete and centralized material is the Jython book. I suggest
a short medium-term strategy of deeplinking into that from the new jython
website, while thinking about how shared material might be refactored and
reindexed as reference and getting started documentation.

I have submitted a PR to fix some simple copyedit things in the current
version of the book as a starting point. It should be useful regardless of
the ultimate direction.
https://github.com/jython/book/pull/4

I went to add the documentation sketch roadmap on the wiki, but it's been a
while since I last logged in, and the password reset emails aren't working
for the emails and usernames I can think of. Is it working for anyone else?
Or can anyone see if there's errors in the server-side log?

Cheers
Adam


On Wed, 24 Apr 2019 at 05:37, Stefan Richthofer <ste...@gm...>
wrote:

> So the application deadline is in half an hour, I suspect it is fairly
> impossible to get this into shape in time.
> Also, it looks like the application would have to be done by the
> organization leader which would be Frank in our case
> or who-ever in PSF case. Some links I just digged out:
>
> https://discuss.python.org/t/will-python-apply-for-season-of-docs-and-allow-suborgs/1105/13
>
> https://discuss.python.org/t/projects-under-psf-that-need-documentation-support/1501
>
> https://numfocus.org/blog/numfocus-projects-to-apply-for-inaugural-google-season-of-docs
>
> So, it kind of looks like PSF does not apply due to lack of projects and
> mentors. NumPy & co applied under NumFocus
> umbrella which is no option for us (?). It looks to me like the whole PSF
> at GSoD idea failed a reasonable incubation
> period this year. Maybe it would be best to achieve this project draft for
> next GSoD and start to incubate things early,
> also check out the option of Jython applying on its own (e.g. if PSF does
> not apply for whatever reason).
>
> Best
>
> -Stefan
>
> Am Di., 23. Apr. 2019 um 21:24 Uhr schrieb Jeff Allen <ja...@fa...
> >:
>
>> Hi Adam:
>>
>> It's a really well-written proposal. I would agree that well describes
>> what needs doing.
>>
>> It would be good to have an author of the Jython book as a mentor,
>> especially if part of the work is to update it. (ISTR Frank once invited us
>> to, so isn't precious about it.) That's the bit I'm least keen to embark on
>> myself, but might be the plumb bit to a technical writer.
>>
>> I'm not sure we can live up to this:
>> https://developers.google.com/season-of-docs/docs/admin-mentor-responsibilities,
>> not as just the Jython project. It all seems to assume a much larger
>> organisation than we have. (As the PSF, sure, but ... .) I barely have the
>> time to encourage people contributing code.
>>
>> Jeff
>>
>> Jeff Allen
>>
>> On 23/04/2019 17:57, James Mudd wrote:
>>
>> Thanks for this Adam
>>
>> I think it would definitely be good to get someone to spend some actual
>> time sorting out the docs, and maybe this is a way to do it. Your
>> suggestion for the project outline looks good to me, I really think there
>> is lots of good stuff out there it just needs consolidating and updating.
>> I'm not on the mentors at the moment but could maybe help with this
>> project. My only concern is I am changing jobs at the start of June and not
>> sure how much time I can offer to help, but if there are a few others
>> available too then I think it could work.
>>
>> James.
>>
>> On Tue, 23 Apr 2019 at 11:57, Adam Burke <ada...@gm...> wrote:
>>
>>> Hi all
>>>
>>> April 23 (today my time) is actually the deadline for mentoring
>>> organizations, which I think is us in the terminology google use.
>>>
>>> https://developers.google.com/season-of-docs/docs/
>>>
>>> Here is a draft proposal. I am not involved with the Python mentor
>>> discussion but please feel free to throw it into the ring. Even if we
>>> aren't selected (or even submitted in time) it can be useful for thinking
>>> about what we want our docs to look like.
>>>
>>> --
>>> Proposal:
>>>
>>> Jython is a well-established and stable pure Java implementation of the
>>> Python interpreter. Over the life of the (15+ year old) project,
>>> documentation has become fragmented and inconsistent. A new github and
>>> markdown documentation project and corresponding website has been
>>> established, but it still needs significant consolidation and reworking of
>>> content from multiple high quality but out of date sources. (The new
>>> project is https://github.com/jython/jython.github.io.) The
>>> documentation could also benefit from the consistency and whole-project
>>> view of a technical writer.
>>>
>>> This project includes
>>>   * Editing and reintegration of archived documentation from versions
>>> 2.1, 2.2 and 2.2.1. This is ht2html generated static HTML from HTML
>>> template source in the jython source repository
>>>   * Repairing the public version of the open soruce Jython book, and
>>> incorporating links to other published Jython books and papers
>>>   * Consolidating release notes from 2.2 - 2.7 in one consistent
>>> location and format
>>>   * Clarifying the focus of the Jython wiki and migrating more official
>>> material from there to the main documentation project (or possibly
>>> deprecating the wiki entirely)
>>>   * Integrating Jython module documentation and having a clear
>>> navigation and dependency mechanism where it extends or varies from Python
>>> libraries. A strength of Jython is that a large proportion of Python
>>> libraries are used unchanged; the documentation should reflect this in a
>>> way useful to both users and Jython core developers.
>>>   * Reviewing and proposing improvements to the structure of the main
>>> documentation project itself
>>>
>>> Stakeholders and mentors for this process would be the Jython core
>>> development team as represented on the jython-dev mailing list,
>>> particularly James Mudd and <X and Y***>.
>>>
>>> --
>>>
>>> *** It would be good to have an experienced core dev, but I am happy to
>>> be involved and named
>>>
>>> Cheers
>>> Adam
>>>
>>> On Wed, 17 Apr 2019 at 09:44, Stefan Richthofer <
>>> ste...@gm...> wrote:
>>>
>>>> By coincidence, while here this discussion about doc started, on the
>>>> core mentorship list someone brought up the idea the PSF should apply at
>>>> https://developers.google.com/season-of-docs/. Maybe we could
>>>> contribute a project suggestion to that discussion. They mainly have
>>>> CPython in mind, but the PSF served as an umbrella organization before in
>>>> GSoC. This new program seems to be organized in a similar way.
>>>>
>>>> Best
>>>>
>>>> -Stefan
>>>>
>>>> Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd <
>>>> 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
>>>>>>
>>>>> _______________________________________________
>>>>> Jython-dev mailing list
>>>>> Jyt...@li...
>>>>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>>>>
>>>> _______________________________________________
>>>> Jython-dev mailing list
>>>> Jyt...@li...
>>>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>>>
>>>
>>
>> _______________________________________________
>> Jython-dev mailing lis...@li...https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
>> _______________________________________________
>> Jython-dev mailing list
>> Jyt...@li...
>> https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
>

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

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

The Jython book is probably the most readable work for beginners to 
Jython. The idea of making it a destination from the project website 
seems good to me. It should work well where the need is to point to 
tutorial material. Thanks for looking at this.

Resetting a password on the Wiki worked for me. I don't appear to have 
any special admin rights that would let me (e.g.) check your e-mail 
address. Maybe Frank or Jim?

Jeff

Jeff Allen

On 25/04/2019 12:46, Adam Burke wrote:
> Have been surveying the current doco, widely if not deeply, and it 
> seems to me the most complete and centralized material is the Jython 
> book. I suggest a short medium-term strategy of deeplinking into that 
> from the new jython website, while thinking about how shared material 
> might be refactored and reindexed as reference and getting started 
> documentation.
>
> I have submitted a PR to fix some simple copyedit things in the 
> current version of the book as a starting point. It should be useful 
> regardless of the ultimate direction.
> https://github.com/jython/book/pull/4
>
> I went to add the documentation sketch roadmap on the wiki, but it's 
> been a while since I last logged in, and the password reset emails 
> aren't working for the emails and usernames I can think of. Is it 
> working for anyone else? Or can anyone see if there's errors in the 
> server-side log?
>
> Cheers
> Adam
>
>
> On Wed, 24 Apr 2019 at 05:37, Stefan Richthofer 
> <ste...@gm... <mailto:ste...@gm...>> wrote:
>
>     So the application deadline is in half an hour, I suspect it is
>     fairly impossible to get this into shape in time.
>     Also, it looks like the application would have to be done by the
>     organization leader which would be Frank in our case
>     or who-ever in PSF case. Some links I just digged out:
>     https://discuss.python.org/t/will-python-apply-for-season-of-docs-and-allow-suborgs/1105/13
>     https://discuss.python.org/t/projects-under-psf-that-need-documentation-support/1501
>     https://numfocus.org/blog/numfocus-projects-to-apply-for-inaugural-google-season-of-docs
>
>     So, it kind of looks like PSF does not apply due to lack of
>     projects and mentors. NumPy & co applied under NumFocus
>     umbrella which is no option for us (?). It looks to me like the
>     whole PSF at GSoD idea failed a reasonable incubation
>     period this year. Maybe it would be best to achieve this project
>     draft for next GSoD and start to incubate things early,
>     also check out the option of Jython applying on its own (e.g. if
>     PSF does not apply for whatever reason).
>
>     Best
>
>     -Stefan
>
>     Am Di., 23. Apr. 2019 um 21:24 Uhr schrieb Jeff Allen
>     <ja...@fa... <mailto:ja...@fa...>>:
>
>         Hi Adam:
>
>         It's a really well-written proposal. I would agree that well
>         describes what needs doing.
>
>         It would be good to have an author of the Jython book as a
>         mentor, especially if part of the work is to update it. (ISTR
>         Frank once invited us to, so isn't precious about it.) That's
>         the bit I'm least keen to embark on myself, but might be the
>         plumb bit to a technical writer.
>
>         I'm not sure we can live up to this:
>         https://developers.google.com/season-of-docs/docs/admin-mentor-responsibilities,
>         not as just the Jython project. It all seems to assume a much
>         larger organisation than we have. (As the PSF, sure, but ...
>         .) I barely have the time to encourage people contributing code.
>
>         Jeff
>
>         Jeff Allen
>
>         On 23/04/2019 17:57, James Mudd wrote:
>>         Thanks for this Adam
>>
>>         I think it would definitely be good to get someone to spend
>>         some actual time sorting out the docs, and maybe this is a
>>         way to do it. Your suggestion for the project outline looks
>>         good to me, I really think there is lots of good stuff out
>>         there it just needs consolidating and updating. I'm not on
>>         the mentors at the moment but could maybe help with this
>>         project. My only concern is I am changing jobs at the start
>>         of June and not sure how much time I can offer to help, but
>>         if there are a few others available too then I think it could
>>         work.
>>
>>         James.
>>
>>         On Tue, 23 Apr 2019 at 11:57, Adam Burke
>>         <ada...@gm... <mailto:ada...@gm...>> wrote:
>>
>>             Hi all
>>
>>             April 23 (today my time) is actually the deadline for
>>             mentoring organizations, which I think is us in the
>>             terminology google use.
>>
>>             https://developers.google.com/season-of-docs/docs/
>>
>>             Here is a draft proposal. I am not involved with the
>>             Python mentor discussion but please feel free to throw it
>>             into the ring. Even if we aren't selected (or even
>>             submitted in time) it can be useful for thinking about
>>             what we want our docs to look like.
>>
>>             --
>>             Proposal:
>>
>>             Jython is a well-established and stable pure Java
>>             implementation of the Python interpreter. Over the life
>>             of the (15+ year old) project, documentation has become
>>             fragmented and inconsistent. A new github and markdown
>>             documentation project and corresponding website has been
>>             established, but it still needs significant consolidation
>>             and reworking of content from multiple high quality but
>>             out of date sources. (The new project is
>>             https://github.com/jython/jython.github.io.) The
>>             documentation could also benefit from the consistency and
>>             whole-project view of a technical writer.
>>
>>             This project includes
>>               * Editing and reintegration of archived documentation
>>             from versions 2.1, 2.2 and 2.2.1. This is ht2html
>>             generated static HTML from HTML template source in the
>>             jython source repository
>>               * Repairing the public version of the open soruce
>>             Jython book, and incorporating links to other published
>>             Jython books and papers
>>               * Consolidating release notes from 2.2 - 2.7 in one
>>             consistent location and format
>>               * Clarifying the focus of the Jython wiki and migrating
>>             more official material from there to the main
>>             documentation project (or possibly deprecating the wiki
>>             entirely)
>>               * Integrating Jython module documentation and having a
>>             clear navigation and dependency mechanism where it
>>             extends or varies from Python libraries. A strength of
>>             Jython is that a large proportion of Python libraries are
>>             used unchanged; the documentation should reflect this in
>>             a way useful to both users and Jython core developers.
>>               * Reviewing and proposing improvements to the structure
>>             of the main documentation project itself
>>
>>             Stakeholders and mentors for this process would be the
>>             Jython core development team as represented on the
>>             jython-dev mailing list, particularly James Mudd and <X
>>             and Y***>.
>>
>>             --
>>
>>             *** It would be good to have an experienced core dev, but
>>             I am happy to be involved and named
>>
>>             Cheers
>>             Adam
>>
>>             On Wed, 17 Apr 2019 at 09:44, Stefan Richthofer
>>             <ste...@gm...
>>             <mailto:ste...@gm...>> wrote:
>>
>>                 By coincidence, while here this discussion about doc
>>                 started, on the core mentorship list someone brought
>>                 up the idea the PSF should apply at
>>                 https://developers.google.com/season-of-docs/. Maybe
>>                 we could contribute a project suggestion to that
>>                 discussion. They mainly have CPython in mind, but the
>>                 PSF served as an umbrella organization before in
>>                 GSoC. This new program seems to be organized in a
>>                 similar way.
>>
>>                 Best
>>
>>                 -Stefan
>>
>>                 Am Di., 16. Apr. 2019 um 21:18 Uhr schrieb James Mudd
>>                 <jam...@gm... <mailto: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... <mailto: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
>>                         <http://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
>>>                         <ja...@fa...
>>>                         <mailto: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...
>>>>                             <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
>>>>>>
>>                         _______________________________________________
>>                         Jython-dev mailing list
>>                         Jyt...@li...
>>                         <mailto:Jyt...@li...>
>>                         https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
>>                     _______________________________________________
>>                     Jython-dev mailing list
>>                     Jyt...@li...
>>                     <mailto:Jyt...@li...>
>>                     https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
>>                 _______________________________________________
>>                 Jython-dev mailing list
>>                 Jyt...@li...
>>                 <mailto:Jyt...@li...>
>>                 https://lists.sourceforge.net/lists/listinfo/jython-dev
>>
>>
>>
>>         _______________________________________________
>>         Jython-dev mailing list
>>         Jyt...@li...  <mailto:Jyt...@li...>
>>         https://lists.sourceforge.net/lists/listinfo/jython-dev
>         _______________________________________________
>         Jython-dev mailing list
>         Jyt...@li...
>         <mailto:Jyt...@li...>
>         https://lists.sourceforge.net/lists/listinfo/jython-dev
>