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