jython-dev — Discussion of developing and enhancing Jython itself(!) (not how to use Jython)

[Jython-dev] JDK 13 - Early Access build 20 is available

[Rory O'D. <ror...@or...>]

*Hi Alan, *


      *OpenJDK builds *- JDK 13 - Early Access build 20 is available at
      http://jdk.java.net/13/

  * These early-access , open-source builds are provided under the
      o GNU General Public License, version 2, with the Classpath
        Exception <http://openjdk.java.net/legal/gplv2+ce.html>.
  * Changes in this build
    <http://hg.openjdk.java.net/jdk/jdk/log?rev=reverse%28%22jdk-13%2B19%22%3A%3A%22jdk-13%2B20%22-%22jdk-13%2B19%22%29&revcount=1000>
  * Release notes [1]


      *Significant changes since the last availability email*

  * build 20
      o Removal of T-Systems Deutsche Telekom Root CA 2 certificate
        (JDK-8222137)
      o Add new FileSystems.newFileSystem methods (JDK-8218875)
      o Enhance auto vectorization for x86 (JDK-8222074)
      o Remove CollectorPolicy and its subclasses (JDK-8198505)
      o Drop support for pre JDK 1.4 SocketImpl implementations
        (JDK-8216978)
  * build 19
      o add support for generating method handles from a variable symbol
        (JDK-8222744)
      o mark new VM option AllowRedefinitionToAddOrDeleteMethods as
        deprecated (JDK-8222934)
  * build 18
      o Improve String::equals warmup characteristics (JDK-8215017)
      o [Containers] Improve systemd slice memory limit support
        (JDK-8217338)


        Bug fixes for issues reported by Open Source Projects

  * build 20
      o assert(Compile::current()->live_nodes() <
        Compile::current()->max_node_limit()) failed: Live Node limit
        exceeded limit (JDK-8219520)
      o C2: MemNode::can_see_stored_value() ignores casts which carry
        control dependency (JDK-8219902)
      o New fix of the deadlock in sun.security.ssl.SSLSocketImpl
        (JDK-8219991)


      JEP updates since last email

  * JEP 350: Dynamic CDS Archives <http://openjdk.java.net/jeps/350> 
    istargeted for JDK 13.
  * JEP 351: ZGC: Uncommit Unused Memory
    <http://openjdk.java.net/jeps/351> istargeted for JDK 13
  * JEP 353: Reimplement the Legacy Socket API
    <http://openjdk.java.net/jeps/353> moved to Candidate
  * JEP 354: Switch Expressions <http://openjdk.java.net/jeps/354> moved
    to Candidate.


      OpenJDK Committers’ Workshop, 1–2 August 2019 [2]

Rgds,Rory

[1] http://jdk.java.net/13/release-notes
[2] https://mail.openjdk.java.net/pipermail/announce/2019-April/000269.html

-- 
Rgds, Rory O'Donnell
Quality Engineering Manager
Oracle EMEA, Dublin, Ireland

Re: [Jython-dev] Maintaining the Definitive Guide to Jython

[Jim B. <jim...@py...>]

Jeff, Adam,

Sounds good about being explicit about the license and the terms &
conditions associated with the PR process, as seen in
https://github.com/jython/book/pull/4/commits/9d67b8136532b14b6ddc172bab38d46937a44070

On Mon, May 6, 2019 at 8:58 PM Jeff Allen <ja...@fa...> wrote:

> Hi Jim,
>
> it's always good to hear that no further admin is necessary. I'll happily
> accept that covers contributions via GitHub, which is probably all.
>
> As GitHub users may not remember theis from the T&Cs they signed up to (I
> didn't), something in the readme/contributing would be good, referencing
> the license and this term already accepted. (I realise the license is on
> the index page.)
>
> Jeff
>
> Jeff Allen
>
> On 06/05/2019 18:44, Jim Baker wrote:
>
> Jeff,
>
> Thanks for bringing this up! It would be great for this book to be updated
> with PRs, which is why we licensed it under CC-SA, wrote it using a source
> text approach, and placed it under repo management.
>
> We also currently have assent support for any PRs per GitHub terms of
> service:
>
> https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license
>
> (See more here:
> https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/
> )
>
> So really there's nothing more to be done on the admin side, as I see it.
>
> - Jim
>
> On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa...> wrote:
>
>> We have a few pull requests against the Jython book in GitHub, and some
>> interest in seeing it updated. The authors hold a copyright, but released
>> it under a Creative Commons 3.0 CC-BY-SA Licence. It publishes
>> automatically via ReadTheDocs. https://jython.readthedocs.io
>>
>> One clear thing is that a modified version must also be released under
>> the same license. Contributors have to assent to that somehow, and this has
>> nothing to do with the license under which the Jython code base is
>> released, or the PSF contributor form. I'm wondering what that assent
>> consists of, and how we keep a record.
>>
>> I found this helpful:
>> https://wiki.creativecommons.org/wiki/Best_practices_for_attribution in
>> forming an idea of what the intention is.
>>
>> The stuff about re-use and derivative works does not perfectly fit the
>> case of publication from a repository, but I think closely enough if one
>> regards the state handed down as an "original" and any current state as
>> either "modified slightly" (after a simple bug-fix) or a "derivative"
>> (after adding a new chapter). The record of change in the repository will
>> do, I think, as a description of who authored what change. Almost
>> everything asked for by CC as attribution is supplied by the context, given
>> the change is *in* the repository.
>>
>> I've seen it suggested each commit/patch should contain a label
>> signifying assent. Elsewhere I've seen a requirement to add oneself to a
>> contributors file, in which could assert the license at the top. It's
>> hardly unforgeable, but evidence of a sort if need be, which it probably
>> never will. Does either of these seem reasonable to us to ask people?
>> Thoughts?
>>
>> Jeff
>>
>> --
>> Jeff Allen
>>
>>

Re: [Jython-dev] Maintaining the Definitive Guide to Jython

[Josh J. <jun...@gm...>]

Hi Jeff,

Thanks for sending.  I'm not sure why that particular file was checked into
the repository.  It is a generated file from Sphinx, and I think it will be
recreated when rebuilt.  I do not believe that you will lose anything by
discarding.

I like your idea of adding a "How to Build This Book" section to the readme.

Thanks!

On Tue, May 7, 2019 at 1:49 AM Jeff Allen <ja...@fa...> wrote:

> Thanks Josh. I understand that you may not be able to help with writing.
> In fact, I'm not sure yet how much we shall do ourselves, but it seems good
> to have the book as a living repository, and it is one place we can explain
> our differences from CPython.
>
> One thing you may be able to clarify ... At some point you checked in the
> generated html (
> https://github.com/jython/book/commit/e41a8089404e8da518294b46523bce516c9f21a6)
> but it is now behind the published state of the book. Do we lose anything
> if we discard this?
>
> So far I only spot the title change and an empty chapter 16 "Web Services
> and SOA". I wouldn't normally check in a build product, although I was
> thinking of adding a "how to build this book" to the readme.
>
> Jeff
>
>
> Jeff Allen
>
> On 06/05/2019 23:55, Josh Juneau wrote:
>
> Hi Jeff/Jim,
>
> I'm very happy to see that the Jython book will be updated!  I don't
> personally have time to help right now but I'm definitely on-board with the
> book being moved forward.
>
> Thanks for all of your time and effort.
>
> Josh Juneau
> jun...@gm...
> http://jj-blogger.blogspot.com
> https://www.apress.com/us/search?query=Juneau
>
> On May 6, 2019, at 5:06 PM, Jeff Allen <ja...@fa...> wrote:
>
> Hi Jim,
>
> it's always good to hear that no further admin is necessary. I'll happily
> accept that covers contributions via GitHub, which is probably all.
>
> As GitHub users may not remember theis from the T&Cs they signed up to (I
> didn't), something in the readme/contributing would be good, referencing
> the license and this term already accepted. (I realise the license is on
> the index page.)
>
> Jeff
>
> Jeff Allen
>
> On 06/05/2019 18:44, Jim Baker wrote:
>
> Jeff,
>
> Thanks for bringing this up! It would be great for this book to be updated
> with PRs, which is why we licensed it under CC-SA, wrote it using a source
> text approach, and placed it under repo management.
>
> We also currently have assent support for any PRs per GitHub terms of
> service:
>
> https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license
>
> (See more here:
> https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/
> )
>
> So really there's nothing more to be done on the admin side, as I see it.
>
> - Jim
>
> On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa...> wrote:
>
>> We have a few pull requests against the Jython book in GitHub, and some
>> interest in seeing it updated. The authors hold a copyright, but released
>> it under a Creative Commons 3.0 CC-BY-SA Licence. It publishes
>> automatically via ReadTheDocs. https://jython.readthedocs.io
>>
>> One clear thing is that a modified version must also be released under
>> the same license. Contributors have to assent to that somehow, and this has
>> nothing to do with the license under which the Jython code base is
>> released, or the PSF contributor form. I'm wondering what that assent
>> consists of, and how we keep a record.
>>
>> I found this helpful:
>> https://wiki.creativecommons.org/wiki/Best_practices_for_attribution in
>> forming an idea of what the intention is.
>>
>> The stuff about re-use and derivative works does not perfectly fit the
>> case of publication from a repository, but I think closely enough if one
>> regards the state handed down as an "original" and any current state as
>> either "modified slightly" (after a simple bug-fix) or a "derivative"
>> (after adding a new chapter). The record of change in the repository will
>> do, I think, as a description of who authored what change. Almost
>> everything asked for by CC as attribution is supplied by the context, given
>> the change is *in* the repository.
>>
>> I've seen it suggested each commit/patch should contain a label
>> signifying assent. Elsewhere I've seen a requirement to add oneself to a
>> contributors file, in which could assert the license at the top. It's
>> hardly unforgeable, but evidence of a sort if need be, which it probably
>> never will. Does either of these seem reasonable to us to ask people?
>> Thoughts?
>>
>> Jeff
>>
>> --
>> Jeff Allen
>>
>> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev
>
> --
Josh Juneau
jun...@gm...
http://jj-blogger.blogspot.com
https://www.apress.com/us/search?query=Juneau
<https://www.apress.com/index.php/author/author/view/id/1866>

Re: [Jython-dev] Maintaining the Definitive Guide to Jython

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

Thanks Josh. I understand that you may not be able to help with writing. 
In fact, I'm not sure yet how much we shall do ourselves, but it seems 
good to have the book as a living repository, and it is one place we can 
explain our differences from CPython.

One thing you may be able to clarify ... At some point you checked in 
the generated html 
(https://github.com/jython/book/commit/e41a8089404e8da518294b46523bce516c9f21a6) 
but it is now behind the published state of the book. Do we lose 
anything if we discard this?

So far I only spot the title change and an empty chapter 16 "Web 
Services and SOA". I wouldn't normally check in a build product, 
although I was thinking of adding a "how to build this book" to the readme.

Jeff

Jeff Allen

On 06/05/2019 23:55, Josh Juneau wrote:
> Hi Jeff/Jim,
>
> I'm very happy to see that the Jython book will be updated!  I don't 
> personally have time to help right now but I'm definitely on-board 
> with the book being moved forward.
>
> Thanks for all of your time and effort.
>
> Josh Juneau
> jun...@gm... <mailto:jun...@gm...>
> http://jj-blogger.blogspot.com <http://jj-blogger.blogspot.com/>
> https://www.apress.com/us/search?query=Juneau
>
> On May 6, 2019, at 5:06 PM, Jeff Allen <ja...@fa... 
> <mailto:ja...@fa...>> wrote:
>
>> Hi Jim,
>>
>> it's always good to hear that no further admin is necessary. I'll 
>> happily accept that covers contributions via GitHub, which is 
>> probably all.
>>
>> As GitHub users may not remember theis from the T&Cs they signed up 
>> to (I didn't), something in the readme/contributing would be good, 
>> referencing the license and this term already accepted. (I realise 
>> the license is on the index page.)
>>
>> Jeff
>>
>> Jeff Allen
>> On 06/05/2019 18:44, Jim Baker wrote:
>>> Jeff,
>>>
>>> Thanks for bringing this up! It would be great for this book to be 
>>> updated with PRs, which is why we licensed it under CC-SA, wrote it 
>>> using a source text approach, and placed it under repo management.
>>>
>>> We also currently have assent support for any PRs per GitHub terms 
>>> of service:
>>> https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license
>>>
>>> (See more here: 
>>> https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/)
>>>
>>> So really there's nothing more to be done on the admin side, as I 
>>> see it.
>>>
>>> - Jim
>>>
>>> On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa... 
>>> <mailto:ja...@fa...>> wrote:
>>>
>>>     We have a few pull requests against the Jython book in GitHub,
>>>     and some interest in seeing it updated. The authors hold a
>>>     copyright, but released it under a Creative Commons 3.0 CC-BY-SA
>>>     Licence. It publishes automatically via ReadTheDocs.
>>>     https://jython.readthedocs.io
>>>
>>>     One clear thing is that a modified version must also be released
>>>     under the same license. Contributors have to assent to that
>>>     somehow, and this has nothing to do with the license under which
>>>     the Jython code base is released, or the PSF contributor form.
>>>     I'm wondering what that assent consists of, and how we keep a
>>>     record.
>>>
>>>     I found this helpful:
>>>     https://wiki.creativecommons.org/wiki/Best_practices_for_attribution
>>>     in forming an idea of what the intention is.
>>>
>>>     The stuff about re-use and derivative works does not perfectly
>>>     fit the case of publication from a repository, but I think
>>>     closely enough if one regards the state handed down as an
>>>     "original" and any current state as either "modified slightly"
>>>     (after a simple bug-fix) or a "derivative" (after adding a new
>>>     chapter). The record of change in the repository will do, I
>>>     think, as a description of who authored what change. Almost
>>>     everything asked for by CC as attribution is supplied by the
>>>     context, given the change is *in* the repository.
>>>
>>>     I've seen it suggested each commit/patch should contain a label
>>>     signifying assent. Elsewhere I've seen a requirement to add
>>>     oneself to a contributors file, in which could assert the
>>>     license at the top. It's hardly unforgeable, but evidence of a
>>>     sort if need be, which it probably never will. Does either of
>>>     these seem reasonable to us to ask people? Thoughts?
>>>
>>>     Jeff
>>>
>>>     -- 
>>>     Jeff Allen
>>>
>> _______________________________________________
>> Jython-dev mailing list
>> Jyt...@li... 
>> <mailto:Jyt...@li...>
>> https://lists.sourceforge.net/lists/listinfo/jython-dev

Re: [Jython-dev] Maintaining the Definitive Guide to Jython

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

Hi all

Great to see this discussion happening.

Have updated the PR to include a note on the license in the new README.md
file
https://github.com/jython/book/pull/4

Cheers
Adam


On Tue, 7 May 2019 at 08:55, Josh Juneau <jun...@gm...> wrote:

> Hi Jeff/Jim,
>
> I'm very happy to see that the Jython book will be updated!  I don't
> personally have time to help right now but I'm definitely on-board with the
> book being moved forward.
>
> Thanks for all of your time and effort.
>
> Josh Juneau
> jun...@gm...
> http://jj-blogger.blogspot.com
> https://www.apress.com/us/search?query=Juneau
>
> On May 6, 2019, at 5:06 PM, Jeff Allen <ja...@fa...> wrote:
>
> Hi Jim,
>
> it's always good to hear that no further admin is necessary. I'll happily
> accept that covers contributions via GitHub, which is probably all.
>
> As GitHub users may not remember theis from the T&Cs they signed up to (I
> didn't), something in the readme/contributing would be good, referencing
> the license and this term already accepted. (I realise the license is on
> the index page.)
>
> Jeff
>
> Jeff Allen
>
> On 06/05/2019 18:44, Jim Baker wrote:
>
> Jeff,
>
> Thanks for bringing this up! It would be great for this book to be updated
> with PRs, which is why we licensed it under CC-SA, wrote it using a source
> text approach, and placed it under repo management.
>
> We also currently have assent support for any PRs per GitHub terms of
> service:
>
> https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license
>
> (See more here:
> https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/
> )
>
> So really there's nothing more to be done on the admin side, as I see it.
>
> - Jim
>
> On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa...> wrote:
>
>> We have a few pull requests against the Jython book in GitHub, and some
>> interest in seeing it updated. The authors hold a copyright, but released
>> it under a Creative Commons 3.0 CC-BY-SA Licence. It publishes
>> automatically via ReadTheDocs. https://jython.readthedocs.io
>>
>> One clear thing is that a modified version must also be released under
>> the same license. Contributors have to assent to that somehow, and this has
>> nothing to do with the license under which the Jython code base is
>> released, or the PSF contributor form. I'm wondering what that assent
>> consists of, and how we keep a record.
>>
>> I found this helpful:
>> https://wiki.creativecommons.org/wiki/Best_practices_for_attribution in
>> forming an idea of what the intention is.
>>
>> The stuff about re-use and derivative works does not perfectly fit the
>> case of publication from a repository, but I think closely enough if one
>> regards the state handed down as an "original" and any current state as
>> either "modified slightly" (after a simple bug-fix) or a "derivative"
>> (after adding a new chapter). The record of change in the repository will
>> do, I think, as a description of who authored what change. Almost
>> everything asked for by CC as attribution is supplied by the context, given
>> the change is *in* the repository.
>>
>> I've seen it suggested each commit/patch should contain a label
>> signifying assent. Elsewhere I've seen a requirement to add oneself to a
>> contributors file, in which could assert the license at the top. It's
>> hardly unforgeable, but evidence of a sort if need be, which it probably
>> never will. Does either of these seem reasonable to us to ask people?
>> Thoughts?
>>
>> Jeff
>>
>> --
>> Jeff Allen
>>
>> _______________________________________________
> 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] Maintaining the Definitive Guide to Jython

[Josh J. <jun...@gm...>]

Hi Jeff/Jim,

I'm very happy to see that the Jython book will be updated!  I don't personally have time to help right now but I'm definitely on-board with the book being moved forward.

Thanks for all of your time and effort.

Josh Juneau
jun...@gm...
http://jj-blogger.blogspot.com
https://www.apress.com/us/search?query=Juneau

> On May 6, 2019, at 5:06 PM, Jeff Allen <ja...@fa...> wrote:
> 
> Hi Jim,
> 
> it's always good to hear that no further admin is necessary. I'll happily accept that covers contributions via GitHub, which is probably all.
> 
> As GitHub users may not remember theis from the T&Cs they signed up to (I didn't), something in the readme/contributing would be good, referencing the license and this term already accepted. (I realise the license is on the index page.)
> 
> Jeff
> 
> Jeff Allen
>> On 06/05/2019 18:44, Jim Baker wrote:
>> Jeff,
>> 
>> Thanks for bringing this up! It would be great for this book to be updated with PRs, which is why we licensed it under CC-SA, wrote it using a source text approach, and placed it under repo management.
>> 
>> We also currently have assent support for any PRs per GitHub terms of service:
>> https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license
>> 
>> (See more here: https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/)
>> 
>> So really there's nothing more to be done on the admin side, as I see it.
>> 
>> - Jim
>> 
>>> On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa...> wrote:
>>> We have a few pull requests against the Jython book in GitHub, and some interest in seeing it updated. The authors hold a copyright, but released it under a Creative Commons 3.0 CC-BY-SA Licence. It publishes automatically via ReadTheDocs. https://jython.readthedocs.io
>>> 
>>> One clear thing is that a modified version must also be released under the same license. Contributors have to assent to that somehow, and this has nothing to do with               the license under which the Jython code base is released, or the PSF contributor form. I'm wondering what that assent consists of, and how we keep a record.
>>> 
>>> I found this helpful: https://wiki.creativecommons.org/wiki/Best_practices_for_attribution in forming an idea of what the intention is.
>>> 
>>> The stuff about re-use and derivative works does not perfectly fit the case of publication from a repository, but I think closely enough if one regards the state handed down as an "original" and any current state as either "modified slightly" (after a simple bug-fix) or a "derivative" (after adding a new chapter). The record of change in the repository will do, I think, as a description of who authored what change. Almost everything asked for by CC as attribution is supplied by the context, given the change is *in* the repository.
>>> 
>>> I've seen it suggested each commit/patch should contain a label signifying assent. Elsewhere I've seen a requirement to add oneself to a contributors file, in which could               assert the license at the top. It's hardly unforgeable, but evidence of a sort if need be, which it probably never will. Does either of these seem reasonable to us to ask people? Thoughts?
>>> 
>>> Jeff
>>> 
>>> -- 
>>> Jeff Allen
> _______________________________________________
> Jython-dev mailing list
> Jyt...@li...
> https://lists.sourceforge.net/lists/listinfo/jython-dev

Re: [Jython-dev] Maintaining the Definitive Guide to Jython

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

Hi Jim,

it's always good to hear that no further admin is necessary. I'll 
happily accept that covers contributions via GitHub, which is probably all.

As GitHub users may not remember theis from the T&Cs they signed up to 
(I didn't), something in the readme/contributing would be good, 
referencing the license and this term already accepted. (I realise the 
license is on the index page.)

Jeff

Jeff Allen

On 06/05/2019 18:44, Jim Baker wrote:
> Jeff,
>
> Thanks for bringing this up! It would be great for this book to be 
> updated with PRs, which is why we licensed it under CC-SA, wrote it 
> using a source text approach, and placed it under repo management.
>
> We also currently have assent support for any PRs per GitHub terms of 
> service:
> https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license
>
> (See more here: 
> https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/)
>
> So really there's nothing more to be done on the admin side, as I see it.
>
> - Jim
>
> On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa... 
> <mailto:ja...@fa...>> wrote:
>
>     We have a few pull requests against the Jython book in GitHub, and
>     some interest in seeing it updated. The authors hold a copyright,
>     but released it under a Creative Commons 3.0 CC-BY-SA Licence. It
>     publishes automatically via ReadTheDocs. https://jython.readthedocs.io
>
>     One clear thing is that a modified version must also be released
>     under the same license. Contributors have to assent to that
>     somehow, and this has nothing to do with the license under which
>     the Jython code base is released, or the PSF contributor form. I'm
>     wondering what that assent consists of, and how we keep a record.
>
>     I found this helpful:
>     https://wiki.creativecommons.org/wiki/Best_practices_for_attribution
>     in forming an idea of what the intention is.
>
>     The stuff about re-use and derivative works does not perfectly fit
>     the case of publication from a repository, but I think closely
>     enough if one regards the state handed down as an "original" and
>     any current state as either "modified slightly" (after a simple
>     bug-fix) or a "derivative" (after adding a new chapter). The
>     record of change in the repository will do, I think, as a
>     description of who authored what change. Almost everything asked
>     for by CC as attribution is supplied by the context, given the
>     change is *in* the repository.
>
>     I've seen it suggested each commit/patch should contain a label
>     signifying assent. Elsewhere I've seen a requirement to add
>     oneself to a contributors file, in which could assert the license
>     at the top. It's hardly unforgeable, but evidence of a sort if
>     need be, which it probably never will. Does either of these seem
>     reasonable to us to ask people? Thoughts?
>
>     Jeff
>
>     -- 
>     Jeff Allen
>

Re: [Jython-dev] Maintaining the Definitive Guide to Jython

[Jim B. <jim...@py...>]

Jeff,

Thanks for bringing this up! It would be great for this book to be updated
with PRs, which is why we licensed it under CC-SA, wrote it using a source
text approach, and placed it under repo management.

We also currently have assent support for any PRs per GitHub terms of
service:
https://help.github.com/en/articles/github-terms-of-service#6-contributions-under-repository-license

(See more here:
https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/
)

So really there's nothing more to be done on the admin side, as I see it.

- Jim

On Sun, May 5, 2019 at 9:14 AM Jeff Allen <ja...@fa...> wrote:

> We have a few pull requests against the Jython book in GitHub, and some
> interest in seeing it updated. The authors hold a copyright, but released
> it under a Creative Commons 3.0 CC-BY-SA Licence. It publishes
> automatically via ReadTheDocs. https://jython.readthedocs.io
>
> One clear thing is that a modified version must also be released under the
> same license. Contributors have to assent to that somehow, and this has
> nothing to do with the license under which the Jython code base is
> released, or the PSF contributor form. I'm wondering what that assent
> consists of, and how we keep a record.
>
> I found this helpful:
> https://wiki.creativecommons.org/wiki/Best_practices_for_attribution in
> forming an idea of what the intention is.
>
> The stuff about re-use and derivative works does not perfectly fit the
> case of publication from a repository, but I think closely enough if one
> regards the state handed down as an "original" and any current state as
> either "modified slightly" (after a simple bug-fix) or a "derivative"
> (after adding a new chapter). The record of change in the repository will
> do, I think, as a description of who authored what change. Almost
> everything asked for by CC as attribution is supplied by the context, given
> the change is *in* the repository.
>
> I've seen it suggested each commit/patch should contain a label signifying
> assent. Elsewhere I've seen a requirement to add oneself to a contributors
> file, in which could assert the license at the top. It's hardly
> unforgeable, but evidence of a sort if need be, which it probably never
> will. Does either of these seem reasonable to us to ask people? Thoughts?
>
> Jeff
>
> --
> Jeff Allen
>
>

[Jython-dev] Maintaining the Definitive Guide to Jython

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

We have a few pull requests against the Jython book in GitHub, and some 
interest in seeing it updated. The authors hold a copyright, but 
released it under a Creative Commons 3.0 CC-BY-SA Licence. It publishes 
automatically via ReadTheDocs. https://jython.readthedocs.io

One clear thing is that a modified version must also be released under 
the same license. Contributors have to assent to that somehow, and this 
has nothing to do with the license under which the Jython code base is 
released, or the PSF contributor form. I'm wondering what that assent 
consists of, and how we keep a record.

I found this helpful: 
https://wiki.creativecommons.org/wiki/Best_practices_for_attribution in 
forming an idea of what the intention is.

The stuff about re-use and derivative works does not perfectly fit the 
case of publication from a repository, but I think closely enough if one 
regards the state handed down as an "original" and any current state as 
either "modified slightly" (after a simple bug-fix) or a "derivative" 
(after adding a new chapter). The record of change in the repository 
will do, I think, as a description of who authored what change. Almost 
everything asked for by CC as attribution is supplied by the context, 
given the change is *in* the repository.

I've seen it suggested each commit/patch should contain a label 
signifying assent. Elsewhere I've seen a requirement to add oneself to a 
contributors file, in which could assert the license at the top. It's 
hardly unforgeable, but evidence of a sort if need be, which it probably 
never will. Does either of these seem reasonable to us to ask people? 
Thoughts?

Jeff

-- 
Jeff Allen

[Jython-dev] Summary of Jython tracker Issues

[Jython t. <st...@bu...>]

ACTIVITY SUMMARY (2019-04-26 - 2019-05-03)
Jython tracker at https://bugs.jython.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open     336 ( +0)
  closed  2428 ( +2)
  total   2764 ( +2)

Open issues with patches: 27   


Issues opened (2)
=================

#2764: Readme is not displayed when using the GUI installer
https://bugs.jython.org/issue2764  opened by jamesmudd

#2766: Oracle JDK 7 out of support so no longer available on Travis
https://bugs.jython.org/issue2766  opened by adamburke



Most recent 15 issues with no replies (15)
==========================================

#2766: Oracle JDK 7 out of support so no longer available on Travis
https://bugs.jython.org/issue2766

#2762: jython-standalone 2.7.1 fails vuln check because of commons-co
https://bugs.jython.org/issue2762

#2760: How to call procedure with use zxjdbc and get back OUT paramet
https://bugs.jython.org/issue2760

#2754: Failure in Py.initProxy for class not at module level
https://bugs.jython.org/issue2754

#2752: Allow Python functions to be used as a java.lang.FunctionalInt
https://bugs.jython.org/issue2752

#2750: Make PyFunction implement java.util.concurrent.Callable<PyObje
https://bugs.jython.org/issue2750

#2736: ensurepip fails with: pip 9.0.1 requires SSL/TLS
https://bugs.jython.org/issue2736

#2734: Re-work package scanning and cache for modules
https://bugs.jython.org/issue2734

#2723: Unusual behavior in SimpleCookie when '=' and '@'  is used in 
https://bugs.jython.org/issue2723

#2722: run-time issue while trying to reach external endpoint (Weathe
https://bugs.jython.org/issue2722

#2720: wrap_scoket_exception: 'module' object has no attribute 'OP_NO
https://bugs.jython.org/issue2720

#2719: Divergence of __str__ and __repr__ from CPython
https://bugs.jython.org/issue2719

#2713: Rounding a float field causes test_cpickle to fail
https://bugs.jython.org/issue2713

#2698: urllib2.URLError: <urlopen error unknown url type: https>
https://bugs.jython.org/issue2698

#2697: name$py.class is ignored when in a JAR with name.py
https://bugs.jython.org/issue2697



Most recent 15 issues waiting for review (15)
=============================================

#2635: AST.lineno ignored by compile
https://bugs.jython.org/issue2635

#2566: inspect does not recognize code objects from bytecode files
https://bugs.jython.org/issue2566

#2545: help() does not work on Java-implemented modules
https://bugs.jython.org/issue2545

#2429: cStringIO does not work with mutable objects implementing the 
https://bugs.jython.org/issue2429

#2367: Jython ignores custom __eq__ when hashing dict subclasses
https://bugs.jython.org/issue2367

#2363: relative seeks works incorrectly after readline
https://bugs.jython.org/issue2363

#2330: full-build fails to copy CPython License
https://bugs.jython.org/issue2330

#2230: Jython evaluation blocks under heavy load with high multi-core
https://bugs.jython.org/issue2230

#2143: site-packages support in standalone jar
https://bugs.jython.org/issue2143

#2142: Set Thread classloader when entering Jython context
https://bugs.jython.org/issue2142

#2121: Jython jar on Maven central embeds other third party libraries
https://bugs.jython.org/issue2121

#2077: marshal doesn't raise error when fed unmarshalable object
https://bugs.jython.org/issue2077

#1925: Support loading java.sql.Drivers that aren't on the boot class
https://bugs.jython.org/issue1925

#1917: No ctypes.c_char
https://bugs.jython.org/issue1917

#1842: Add IBM i support to Jython
https://bugs.jython.org/issue1842



Top 10 most discussed issues (2)
================================

#2764: Readme is not displayed when using the GUI installer
https://bugs.jython.org/issue2764   7 msgs

#2445: Eclipse's DelegatingFeatureMap has MRO conflict (and IBM's MQQ
https://bugs.jython.org/issue2445   4 msgs



Issues closed (2)
=================

#2666: Imports in python from java do not work if there is a package 
https://bugs.jython.org/issue2666  closed by jeff.allen

#2758: Need Multi dimension jarrays 2D and 3D
https://bugs.jython.org/issue2758  closed by jeff.allen

[Jython-dev] Summary of Jython tracker Issues

[Jython t. <st...@bu...>]

ACTIVITY SUMMARY (2019-04-19 - 2019-04-26)
Jython tracker at https://bugs.jython.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open     336 ( +1)
  closed  2426 ( +0)
  total   2762 ( +1)

Open issues with patches: 27   


Issues opened (1)
=================

#2762: jython-standalone 2.7.1 fails vuln check because of commons-co
https://bugs.jython.org/issue2762  opened by dwichers



Most recent 15 issues with no replies (15)
==========================================

#2762: jython-standalone 2.7.1 fails vuln check because of commons-co
https://bugs.jython.org/issue2762

#2760: How to call procedure with use zxjdbc and get back OUT paramet
https://bugs.jython.org/issue2760

#2754: Failure in Py.initProxy for class not at module level
https://bugs.jython.org/issue2754

#2752: Allow Python functions to be used as a java.lang.FunctionalInt
https://bugs.jython.org/issue2752

#2750: Make PyFunction implement java.util.concurrent.Callable<PyObje
https://bugs.jython.org/issue2750

#2736: ensurepip fails with: pip 9.0.1 requires SSL/TLS
https://bugs.jython.org/issue2736

#2734: Re-work package scanning and cache for modules
https://bugs.jython.org/issue2734

#2723: Unusual behavior in SimpleCookie when '=' and '@'  is used in 
https://bugs.jython.org/issue2723

#2722: run-time issue while trying to reach external endpoint (Weathe
https://bugs.jython.org/issue2722

#2720: wrap_scoket_exception: 'module' object has no attribute 'OP_NO
https://bugs.jython.org/issue2720

#2719: Divergence of __str__ and __repr__ from CPython
https://bugs.jython.org/issue2719

#2713: Rounding a float field causes test_cpickle to fail
https://bugs.jython.org/issue2713

#2698: urllib2.URLError: <urlopen error unknown url type: https>
https://bugs.jython.org/issue2698

#2697: name$py.class is ignored when in a JAR with name.py
https://bugs.jython.org/issue2697

#2684: WindowsError:[Error 123] The filename,directory name,or volume
https://bugs.jython.org/issue2684



Most recent 15 issues waiting for review (15)
=============================================

#2635: AST.lineno ignored by compile
https://bugs.jython.org/issue2635

#2566: inspect does not recognize code objects from bytecode files
https://bugs.jython.org/issue2566

#2545: help() does not work on Java-implemented modules
https://bugs.jython.org/issue2545

#2429: cStringIO does not work with mutable objects implementing the 
https://bugs.jython.org/issue2429

#2367: Jython ignores custom __eq__ when hashing dict subclasses
https://bugs.jython.org/issue2367

#2363: relative seeks works incorrectly after readline
https://bugs.jython.org/issue2363

#2330: full-build fails to copy CPython License
https://bugs.jython.org/issue2330

#2230: Jython evaluation blocks under heavy load with high multi-core
https://bugs.jython.org/issue2230

#2143: site-packages support in standalone jar
https://bugs.jython.org/issue2143

#2142: Set Thread classloader when entering Jython context
https://bugs.jython.org/issue2142

#2121: Jython jar on Maven central embeds other third party libraries
https://bugs.jython.org/issue2121

#2077: marshal doesn't raise error when fed unmarshalable object
https://bugs.jython.org/issue2077

#1925: Support loading java.sql.Drivers that aren't on the boot class
https://bugs.jython.org/issue1925

#1917: No ctypes.c_char
https://bugs.jython.org/issue1917

#1842: Add IBM i support to Jython
https://bugs.jython.org/issue1842

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
>

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?

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

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

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

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

[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

[Jython-dev] Summary of Jython tracker Issues

[Jython t. <st...@bu...>]

ACTIVITY SUMMARY (2019-04-12 - 2019-04-19)
Jython tracker at https://bugs.jython.org/

To view or respond to any of the issues listed below, click on the issue.
Do NOT respond to this message.

Issues counts and deltas:
  open     335 ( +1)
  closed  2426 ( +0)
  total   2761 ( +1)

Open issues with patches: 27   


Issues opened (1)
=================

#2760: How to call procedure with use zxjdbc and get back OUT paramet
https://bugs.jython.org/issue2760  opened by youlfey



Most recent 15 issues with no replies (15)
==========================================

#2760: How to call procedure with use zxjdbc and get back OUT paramet
https://bugs.jython.org/issue2760

#2754: Failure in Py.initProxy for class not at module level
https://bugs.jython.org/issue2754

#2752: Allow Python functions to be used as a java.lang.FunctionalInt
https://bugs.jython.org/issue2752

#2750: Make PyFunction implement java.util.concurrent.Callable<PyObje
https://bugs.jython.org/issue2750

#2736: ensurepip fails with: pip 9.0.1 requires SSL/TLS
https://bugs.jython.org/issue2736

#2734: Re-work package scanning and cache for modules
https://bugs.jython.org/issue2734

#2723: Unusual behavior in SimpleCookie when '=' and '@'  is used in 
https://bugs.jython.org/issue2723

#2722: run-time issue while trying to reach external endpoint (Weathe
https://bugs.jython.org/issue2722

#2720: wrap_scoket_exception: 'module' object has no attribute 'OP_NO
https://bugs.jython.org/issue2720

#2719: Divergence of __str__ and __repr__ from CPython
https://bugs.jython.org/issue2719

#2713: Rounding a float field causes test_cpickle to fail
https://bugs.jython.org/issue2713

#2698: urllib2.URLError: <urlopen error unknown url type: https>
https://bugs.jython.org/issue2698

#2697: name$py.class is ignored when in a JAR with name.py
https://bugs.jython.org/issue2697

#2684: WindowsError:[Error 123] The filename,directory name,or volume
https://bugs.jython.org/issue2684

#2680: Ignore Java accessibility rules selectively by package (Java 9
https://bugs.jython.org/issue2680



Most recent 15 issues waiting for review (15)
=============================================

#2635: AST.lineno ignored by compile
https://bugs.jython.org/issue2635

#2566: inspect does not recognize code objects from bytecode files
https://bugs.jython.org/issue2566

#2545: help() does not work on Java-implemented modules
https://bugs.jython.org/issue2545

#2429: cStringIO does not work with mutable objects implementing the 
https://bugs.jython.org/issue2429

#2367: Jython ignores custom __eq__ when hashing dict subclasses
https://bugs.jython.org/issue2367

#2363: relative seeks works incorrectly after readline
https://bugs.jython.org/issue2363

#2330: full-build fails to copy CPython License
https://bugs.jython.org/issue2330

#2230: Jython evaluation blocks under heavy load with high multi-core
https://bugs.jython.org/issue2230

#2143: site-packages support in standalone jar
https://bugs.jython.org/issue2143

#2142: Set Thread classloader when entering Jython context
https://bugs.jython.org/issue2142

#2121: Jython jar on Maven central embeds other third party libraries
https://bugs.jython.org/issue2121

#2077: marshal doesn't raise error when fed unmarshalable object
https://bugs.jython.org/issue2077

#1925: Support loading java.sql.Drivers that aren't on the boot class
https://bugs.jython.org/issue1925

#1917: No ctypes.c_char
https://bugs.jython.org/issue1917

#1842: Add IBM i support to Jython
https://bugs.jython.org/issue1842



Top 10 most discussed issues (1)
================================

#2445: Eclipse's DelegatingFeatureMap has MRO conflict
https://bugs.jython.org/issue2445   4 msgs

[Jython-dev] JDK 13 - Early Access build 17 is available

[Rory O'D. <ror...@or...>]

*Hi Alan, *

*OpenJDK builds *- JDK 13 - Early Access build 17 is available at 
http://jdk.java.net/13/

  * These early-access , open-source builds are provided under the
      o GNU General Public License, version 2, with the Classpath
        Exception <http://openjdk.java.net/legal/gplv2+ce.html>.
  * Changes in this build
    <http://hg.openjdk.java.net/jdk/jdk/log?rev=reverse%28%22jdk-13%2B16%22%3A%3A%22jdk-13%2B17%22-%22jdk-13%2B16%22%29&revcount=1000>
  * Release notes [1]

*Significant changes since the last availability email*

  * build 16 - Update the default enabled cipher suites preference
    (JDK-8163326 <https://bugs.openjdk.java.net/browse/JDK-8163326>)
  * build 16 - Add new keytool -showinfo -tls command for displaying TLS
    configuration information (JDK-8219861
    <https://bugs.openjdk.java.net/browse/JDK-8219861>)
  * build 15  -*New Japanese Era Name **(JDK-8205432
    <https://bugs.openjdk.java.net/browse/JDK-8205432>)*
  * build 15  - Accessing REIWA era in java.time.chrono.JapaneseEra
    (JDK-8174268 <https://bugs.openjdk.java.net/browse/JDK-8174268>)
  * build 15  - Duplicated RSA services are no longer supported by
    SunJSSE provider (JDK-8220016
    <https://bugs.openjdk.java.net/browse/JDK-8220016>)
  * build 15  - Use server cipher suites preference by default
    (JDK-8168261 <https://bugs.openjdk.java.net/browse/JDK-8168261>)
  * build 15  - The Swing Motif Look and Feel is deprecated and
    unsupported on macOS (JDK-8177960
    <https://bugs.openjdk.java.net/browse/JDK-8177960>)
  * build 15  - Remove support for javadoc "frames" mode (JDK-8215599
    <https://bugs.openjdk.java.net/browse/JDK-8215599>)

Bug fix reported by Open Source Projects  :

  * build 15  - Unable to read certain PKCS12 keystores from
    SequenceInputStream (JDK-8157404)
    <https://bugs.openjdk.java.net/browse/JDK-8157404>

*April 2019 CPU Released*

  * As part of the Apr 2019 Critical Patch Update we released OpenJDK
    12.0.1  under the GNU General Public License, version 2, with the
    Classpath Exception <http://openjdk.java.net/legal/gplv2+ce.html>. [2]
  * One change previously announced in the Java Cryptographic Roadmap [3]

*Request for feedback *-  switch expressions in JDK 12  , feedback via 
amber-dev list [4]

Rgds,Rory

[1] http://jdk.java.net/13/release-notes
[2] http://jdk.java.net/12
[3] https://java.com/en/jre-jdk-cryptoroadmap.html
[4] https://mail.openjdk.java.net/pipermail/jdk-dev/2019-April/002770.html

-- 
Rgds, Rory O'Donnell
Quality Engineering Manager
Oracle EMEA, Dublin, Ireland

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?

[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...>]

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?

[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...>]

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