Menu
▾
▴
Re: [Jython-dev] Where to add documentation details about jarray / registry?
|
From: Jeff A. <ja...@fa...> - 2019-04-23 19:23:39
|
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 |
