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