Packaging Python Projects: Add/update links to other docs #908
Conversation
| :doc:`Including Data Files <setuptools:userguide/datafiles>` | ||
| from the :doc:`setuptools docs <setuptools:index>`. |
There was a problem hiding this comment.
I don't know what :std: is supposed to do, but it doesn't seem necessary...
There was a problem hiding this comment.
Some the roles are namespaced and this is the default namespace. It is probably coming from https://webknjaz.github.io/intersphinx-untangled/ as it outputs full role names in the examples column.
There was a problem hiding this comment.
It is probably coming from https://webknjaz.github.io/intersphinx-untangled/
I don't understand this.
Looks like @henryiii added this section two months ago. However, there are other intersphinx links to setuptools that don't use :std:, e.g.:
So I'm inclined to leave it out.
There was a problem hiding this comment.
I don't understand this.
That's my pet project that renders all the objects that different Sphinx sites expose. If you link against one of such sites, besides adding them to intersphinx_mapping, you normally need to know the names and the types of the objects documented there. One way is to do it with a CLI command that sphinx provides but the output is rather poorly structured so this page outputs the same info as a table and I've added examples of how people could link each object in their docs.
Things may be :std:doc: or :py:mod:, for example. Those are full names of the object roles. But one role may be set up as default and that is usually std. So if one omits that and uses just :doc:, sphinx will automatically assume that it's :std:doc: under the hood.
But when outputting the intersphinx data, the full name is always encoded internally so that's what this site shows. And my guess was that this full syntax used in the document has simply been copy-pasted from my project.
FWIW both variants work. I hope that this attempt to explain :std: doesn't sound too confusing...
P.S. Maybe this https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html will shed more light on the roles..
There was a problem hiding this comment.
Thanks for the explanation, and your pet project. I totally missed that clicking on those links would take you to something like https://webknjaz.github.io/intersphinx-untangled/setuptools.rtfd.io/; I just assumed they linked to the named sites. I think adding some explanatory text on the index would make it even more useful. 😅
There was a problem hiding this comment.
Oh, that's a good idea. I just didn't invest into that too much time after I got what I needed for myself :)
But I'll definitely consider that or accept any improvement PRs (because I don't hope to have any time for this right now).
|
@webknjaz Could you take a look at this? |
Towards #866.
This is mostly adding more links glossary entries, with a couple more substantial changes that felt related.