dev-python/python-docs currently installs files in /usr/share/doc/${PF}/html. This is undesirable for a couple of reasons: 1. It is difficult to bookmark in a browser across minor version bumps. 2. As has been pointed out by Ian in a recent mailing list post, intersphinx needs to access objects.inv when building docs for other packages. It would be helpful to have this file in a predictable location. Here is what I propose: A. python-docs installs its files in /usr/share/doc/${PN}-${SLOT} B. A pkg_postinst / pkg_postrm call will maintain a symlink at /usr/share/doc/python-docs which points at the latest installed version. Any objections or better ideas?
I don't like the idea of reusing /usr/share/doc with another naming scheme. Does sphinx have any specific location hardcoded btw?
None that I know of. Docs for reference: http://sphinx-doc.org/ext/intersphinx.html
(In reply to Michał Górny from comment #1) > I don't like the idea of reusing /usr/share/doc with another naming scheme. Why not? It's a slotted dependency, so there won't be conflicts for slot-level namespacing. > Does sphinx have any specific location hardcoded btw? No, it's just hardcoded in the consumer's intersphinx_mapping [1,2]. For (B), I'd propose we link to the 2.7 slot, and fall back to the highest 3.x slot if there isn't an installed version of python-docs in the 2.7 slot. That matches PEP 430 [3] and https://docs.python.org/objects.inv. [1]: http://sphinx-doc.org/latest/ext/intersphinx.html#confval-intersphinx_mapping [2]: https://github.com/wcdolphin/flask-cors/blob/v1.8.0/docs/conf.py#L259 [3]: http://legacy.python.org/dev/peps/pep-0430/#don-t-break-useful-resources
(In reply to W. Trevor King from comment #3) > For (B), I'd propose we link to the 2.7 slot, and fall back to the > highest 3.x slot if there isn't an installed version of python-docs in > the 2.7 slot. That matches PEP 430 [3] and > https://docs.python.org/objects.inv. Oh, we'll probably want additional symlinks for /usr/share/doc/${PN}-2 and 3, to match http://docs.python.org/2/objects.inv and http://docs.python.org/3/objects.inv. For easier maintenance, ${PN}-2 can just point to ${PN}.
Another possible location would be /usr/share/python-docs, which would keep us from messing with the /usr/share/doc naming convention.
A less intrusive solution would be to leave the files where they are, and create some symlinks /usr/share/python-docs.
(In reply to Mike Gilbert from comment #0) > 2. As has been pointed out by Ian in a recent mailing list post, intersphinx > needs to access objects.inv when building docs for other packages. It would > be helpful to have this file in a predictable location. This stable-symlink approach to providing unversioned, 2.x, 3.x, and slot-level symlinks is ok for python-docs, because it matches upstream's approach with docs.python.org. I don't think it's going to scale well for other packages with Sphinx-based docs that act as intersphins targets, though. For example, Matplotlib's Sphinx docs will have an objects.inv, but dev-python/matplotlib-9999 currently uses distutils-r1's HTML_DOCS to install it's docs. That's not going to intall objects.inv, but even if it did, it would be touchy to have a matplotlib client linking into /usr/share/docs/matplotlib-1.2.0-r2 and unweildy to link into /usr/share/matplotlib-docs/1.3 (etc., etc., for every other Sphinx-based package).
Maybe it doesn't do what you want but no one has mentioned the existing symlink: /usr/share/doc/html/dev-python/python-docs-${SLOT}
(In reply to Chris Mayo from comment #8) > Maybe it doesn't do what you want but no one has mentioned the existing > symlink: > /usr/share/doc/html/dev-python/python-docs-${SLOT} I don't have that link locally. Do you know where yours came from?
He probably has DOC_SYMLINKS_DIR set in make.conf. DOC_SYMLINKS_DIR If this variable contains a directory then symlinks to html documentation will be installed into it.
(In reply to Mike Gilbert from comment #10) > He probably has DOC_SYMLINKS_DIR set in make.conf. That's not in the PMS, so I think it's probably off-limits in an ebuild that needs access to an objects.inv file. Portage's 507bae0b (create symlinks to html documentation if DOC_SYMLINK_DIR is set, 2007-01-10) doesn't explain why you'd want something like this anyway ;). Perhaps it's for the bookmark reason you mention in the original comment? In any case, a solution that works for both users and ebuilds would be better ;).
Do we have any consensus on a final generic from of sulution? Last entry 2 weeks. If nothing else, the form in the now present and bumped flask-cors to me would suffice. It's a template since the entry in conf.py may need a tweak form package to package. Already found one
Given the complexity of a generic solution for the intersphinx problem, and the relative utility of having hyperlinks to external documentation for the standard library, I don't think it really makes sense to implement this.
(In reply to Mike Gilbert from comment #13) > Given the complexity of a generic solution for the intersphinx problem, … It's not particularly complicated. Figuring out which packages are satisfying an or-clause dependency and locating one of their installed files by name are both simple concepts. I think the main blocker is that there's currently no way to do either of these, and the benefit may not be worth the trouble of pushing through a PMS update (i.e. “the PMS is too heavy”, not “a generic solution is complex”). > … and the relative utility of having hyperlinks to external documentation > for the standard library, … Are you saying that linking out to external documentation is more useful than linking to local docs? If you're in that camp, I don't see why you'd enable the 'doc' flag at all ;). Anyway, we shouldn't be hitting the network to download the objects.inv files at build time [1], and I don't have a solution to versioning any objects.inv files a build depends on thats any simpler than the one proposed here. [1]: https://bugs.gentoo.org/show_bug.cgi?id=522064
(In reply to W. Trevor King from comment #14) I'm saying that I don't think it makes sense to mess with a bunch of packages so that we can generate hyperlinks to a local copy of the python docs. It's just not worth it. As for the "don't fetch from the network thing", that's pretty minor. If the network is unavailable, nothing breaks except for a few hyperlinks.
As floppym said. If we were able to install the Sphinx docs in such a way that intersphinx would find them automatically, that would be a different thing. But I don't think any of us is able to work on that right now. If you are interested, please look into patching the Sphinx code. Not sure how feasible that would be, and whether upstream will be really interested in applying it. For a start, you would have to be able to map URIs into local directories for all packages. We could probably change the install location then, but you'd also have them to install some kind of index file... also, note that for the case of python-docs, the mapping would have to recognize different locations for different python versions. In other words, unlikely and a lot of work.
I'm reopening this because I think problem #1 is worth solving, regardless of the intersphinx issue. If it makes the intersphinx sed-hack (which I still don't really like) simpler, we will count that as a bonus.
Earlier today on #gentoo-python I said I was fine with /usr/share/doc/${PN}/${SLOT} symlinks (or some variation on that name), but I've since come back to my earlier position: (In reply to W. Trevor King from comment #14) > It's not particularly complicated. Figuring out which packages are > satisfying an or-clause dependency and locating one of their installed files > by name are both simple concepts. I think the main blocker is that there's > currently no way to do either of these, and the benefit may not be worth the > trouble of pushing through a PMS update (i.e. “the PMS is too heavy”, not “a > generic solution is complex”). Letting the "locating one of their installed files" bit slip for now, the symlink approach allows us to tiptoe around figuring out which package satisfies a dependency (e.g. if you asked for python-docs:2.7, you can just use the …/2.7 symlink without figuring out that it's 2.7.8 and using …/python-docs-2.7.8/). I'd rather have something give me atoms for “what package satifsies "${DEPENDENCY_CLAUSE}"”. That's basically an extension of best_version (lets call it satisfied_by). Then you could have: PYTHON_DOCS_DEPENDS="|| ( dev-python/python-docs:2.7 dev-python/python-docs:3.3 … ) DEPENDS="${PYTHON_DOCS_DEPENDS} …" … python_prepare_all() { if use doc; then local PYTHON_DOC_ATOM=$(satisfied_by --host-root "${PYTHON_DOCS_DEPENDS}") … fi } Of course, a naive satisfied_by is not going to be able to traverse the dependency tree (e.g. to look past virtual/* dependencies). It's hard to write a clean API for that in Bash though. What you'd want is access to a Portage's parsed dependency tree in Python. So until we land a pure-Python EAPI, I think we have to either use /usr/share/doc/${PN}/${SLOT} symlinks for all installed packages, or just stick to the cases we can already handle with best_version.
good thoughts. "What you'd want is access to a Portage's parsed dependency tree in Python." Careful we don't overload the requirements to get this to work. "or just stick to the cases we can already handle with best_version" it appears would keep this 'manageable', though once we get a working form, we' (I) can add to it at leisure. What makes this whole exercise difficult is it starts out with "the intersphinx sed-hack". which frankly is easy not to like. However, imho, we need get past that and accept it will require a use of the lesser of the choice of evils. In other words, compromise; something that is just part of 'real life'.
(In reply to Ian Delaney from comment #19) > However, imho, we need get past that and accept it will require a > use of the lesser of the choice of evils. An even "lesser evil" would be to leave it alone and not apply the sed hack. It's a half-baked solution to a very minor problem.
I'm with Mike!
So how about /usr/share/sphinx-docs/python-{2.7,3.3,3.4,...}? That looks quite sane and keeps the potential of installing future application docs there. Since that's not the only problem with Sphinx-generated docs, we may want to provide a more complete solution that covers bug #526186 (filtered files) as well.
(In reply to Michał Górny from comment #22) > So how about /usr/share/sphinx-docs/python-{2.7,3.3,3.4,...}? That looks > quite sane and keeps the potential of installing future application docs > there. Since that's not the only problem with Sphinx-generated docs, we may > want to provide a more complete solution that covers bug #526186 (filtered > files) as well. I still think that we should have generic solutions to the genric problems [1]. In this case, I'm fine just using best_version. We currently use best_version to get the full version number (in flask-cors[doc] and similar), are folks really that unhappy about that approach? In the next week or so, I hope to have an initial sphinx.eclass that abstracts away the current best_version through intersphinx sed stuff into an: sphinx_local_objects LINKED_PACKAGE_DEPENDENCY SED_REGEX_MATCHINGsphinx_local_objects_THE_UPSTREAM_INTERSPHINX_ENTRY PATH_TO_CONF_PY so, for example, the flask-cors doc patch would look like: sphinx_local_objects dev-python/python-docs:2.7 "'http://docs.python.org/': None" docs/conf.py How does that sound? A Sphinx eclass would also be a good place for a dosphinx helper. [1]: https://bugs.gentoo.org/show_bug.cgi?id=522794#c18
No action for 3.5yr. Feel free to reopen if somebody decides to actually pursue it with code.
