Re: Where to add documentation details about jarray / registry?
Jeff Allen <[email protected]>
| Newsgroups | gmane.comp.lang.jython.devel |
|---|---|
| Message-ID | <[email protected]> |
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 > <[email protected] <mailto:[email protected]>> 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 > <[email protected] <mailto:[email protected]>>: > > 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 >> <[email protected] <mailto:[email protected]>> 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 >> <[email protected] >> <mailto:[email protected]>> 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 >> <[email protected] <mailto:[email protected]>>: >> >> 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 >> <[email protected] <mailto:[email protected]>> >> 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 >>> <[email protected] >>> <mailto:[email protected]>> wrote: >>> >>> What exactly do you mean by "the new git >>> docs"? I don't think we have Jython user >>> docs in git, only developer docs. >>> There's an old one in hg I think. >>> >>> The developer docs were a bit of an >>> experiment. In the developer docs, the >>> idea was to keep all the CPython content >>> but create additional Jython pages, >>> including a replacement start page. I >>> kept the CPython pages so changes from >>> upstream still update them. Some of the >>> pages don't work at all for Jython, so >>> are not in the main index, and are >>> present so upstream change has somewhare >>> to land. Others remain valid for Jython, >>> or are valid with small modifications >>> (to be merged with care). >>> >>> I don't know if we can inherit the >>> CPython user docs in the same way, but >>> I'm happy to see it tried. One needs to >>> take the docs of the target version of >>> CPython we are most like. It will take >>> significant editing initially, but won't >>> need much change while the target >>> version is the same. Maybe there *is* no >>> upstream change to speak of. When we >>> advance that target version, what >>> happens? My main critereon is that we >>> don't create a thing we can't afford to >>> maintain. >>> >>> Jeff >>> >>> Jeff Allen >>> >>> On 14/04/2019 02:57, Adam Burke wrote: >>>> > (isn't it neat!) >>>> >>>> Yes, and in a lovely jythonesque way : ) >>>> >>>> On the docs, I guess I agree that you >>>> want to inherit the CPython docs, plus >>>> being able to note variations in >>>> Jython, plus some pages on >>>> Jython-specific elements. This might >>>> just be a separate index to module >>>> documentation, say for jarray, or it >>>> might be specific language features, >>>> like Java imports. (And a website to >>>> put it on, indeed.) >>>> >>>> If there is not a specific target area >>>> already for Jython specific features, I >>>> will send a doc patch carving out an >>>> area in the new git docs. This should >>>> not interfere much with any later work >>>> to synch with the CPython docs. I will >>>> probably copy some of the 2.1 archive >>>> material linked below. >>>> >>>> Cheers >>>> Adam >>>> >>>> 在 2019年4月14日，上午2:26，Jeff Allen >>>> <[email protected] >>>> <mailto:[email protected]>> 写道： >>>> >>>>> Thanks for responding on that. I >>>>> didn't know the answer off the top of >>>>> my head (isn't it neat!), but thought >>>>> you, James or Stefan might. I was once >>>>> told jarray was not much used, meaning >>>>> en route to deprecation, but until >>>>> there is a compatible ndarray ... . >>>>> >>>>> Ideally we whould have a set of >>>>> documentation that is a copy of the >>>>> CPython one with amendements. (And a >>>>> web site to put it on.) But it's work. >>>>> We might get away increasingly with >>>>> referring to the CPython documents, >>>>> because of increasing conformance to >>>>> expectations created by CPython. It >>>>> will never really reduce the need to >>>>> zero, however. I don't know how >>>>> affordably to maintain a large >>>>> document that is only a little >>>>> different from CPython's. I had a go >>>>> with the dev-guide and think it saved >>>>> work to borrow by forking, but it was >>>>> still a fair amount of effort and not >>>>> wholly successful in keeping up. >>>>> >>>>> Language and module documentation has >>>>> a different balance, though. >>>>> >>>>> I think an approach that mimics >>>>> CPython's structurally, but contains >>>>> only notes about differences would >>>>> work and a link to the CPython doc. >>>>> It's a good reason to have a clearer >>>>> answer to "what CPython are you most >>>>> like" than we can normally give, since >>>>> that's the version we would link. >>>>> Where to put it though? >>>>> >>>>> Jeff Allen >>>>> On 13/04/2019 12:53, Adam Burke wrote: >>>>>> There was a bug raised today which is >>>>>> already a feature, and really just >>>>>> points to a documentation gap. I made >>>>>> a comment there, and was going to add >>>>>> some doc, so went for the right place >>>>>> to enhance pages on the jarray >>>>>> module. Basically I was expecting to >>>>>> add a few lines to a page like this >>>>>> (which still turns up high on google) >>>>>> >>>>>> https://www.jython.org/archive/21/docs/jarray.html >>>>>> >>>>>> >>>>>> However it seems jython specific >>>>>> details like jarray or the jython >>>>>> registry might have been victims of >>>>>> multiple documentation moves over the >>>>>> years since v2.1. I started looking >>>>>> on the new jython doco git project >>>>>> and moved out from there. There >>>>>> doesn't appear to be anything on the >>>>>> wiki either. >>>>>> >>>>>> That all being what it is - can >>>>>> someone point me to either an >>>>>> existing place to add to this, or >>>>>> where would the right place to add >>>>>> *back* a page on jarray in the target >>>>>> documentation structure? >>>>>> >>>>>> Cheers >>>>>> Adam >>>>>> >> _______________________________________________ >> Jython-dev mailing list >> [email protected] >> <mailto:[email protected]> >> https://lists.sourceforge.net/lists/listinfo/jython-dev >> >> _______________________________________________ >> Jython-dev mailing list >> [email protected] >> <mailto:[email protected]> >> https://lists.sourceforge.net/lists/listinfo/jython-dev >> >> _______________________________________________ >> Jython-dev mailing list >> [email protected] >> <mailto:[email protected]> >> https://lists.sourceforge.net/lists/listinfo/jython-dev >> >> >> >> _______________________________________________ >> Jython-dev mailing list >> [email protected] <mailto:[email protected]> >> https://lists.sourceforge.net/lists/listinfo/jython-dev > _______________________________________________ > Jython-dev mailing list > [email protected] > <mailto:[email protected]> > https://lists.sourceforge.net/lists/listinfo/jython-dev > _______________________________________________ Jython-dev mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/jython-dev