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