Menu
▾
▴
Re: [Jython-dev] Where to add documentation details about jarray / registry?
|
From: Stefan R. <ste...@gm...> - 2019-04-23 19:38:02
|
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 > |
