-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New Sphinx tutorial (intersphinx, postponed) #9424
Changes from all commits
0bea92d
06824e2
9dade12
8511726
89aa4f9
87c3650
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -267,7 +267,7 @@ follows: | |
'sphinx.ext.duration', | ||
] | ||
|
||
After that, every time you generate your documentation, you will see a short | ||
After that, every time you build your documentation, you will see a short | ||
durations report at the end of the console output, like this one: | ||
|
||
.. code-block:: console | ||
|
@@ -437,13 +437,74 @@ And make the sentence you added in ``index.rst`` look like this: | |
:ref:`install <installation>` the project. | ||
|
||
Notice a trick here: the ``install`` part specifies how the link will look like | ||
(we want it to be a specific word, so the sentence makes sense), whereas the | ||
``<installation>`` part refers to the actual label we want to add a | ||
(in this case, using a specific word so the sentence makes sense), whereas the | ||
``<installation>`` part refers to the actual label you want to add a | ||
cross-reference to. If you do not include an explicit title, hence using | ||
``:ref:`installation```, the section title will be used (in this case, | ||
``Installation``). Both the ``:doc:`` and the ``:ref:`` roles will be rendered | ||
as hyperlinks in the HTML documentation. | ||
|
||
Referencing external projects with intersphinx | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
You are likely depending on some open source libraries for your own | ||
project, and there is a chance those dependencies have their documentation | ||
written in Sphinx and available online. One of the powerful features of | ||
Sphinx is the ability to generate cross-references to other | ||
projects available online, using the | ||
:doc:`intersphinx </usage/extensions/intersphinx>` extension. | ||
|
||
To enable it, first add ``sphinx.ext.intersphinx`` to the list of extensions: | ||
|
||
.. code-block:: python | ||
:caption: docs/source/conf.py | ||
|
||
extensions = [ | ||
'sphinx.ext.duration', | ||
'sphinx.ext.intersphinx', | ||
] | ||
|
||
The way to know whether you can reference an external project is to check | ||
if it has a publicly available ``objects.inv``, which can be parsed calling | ||
``python -m sphinx.ext.intersphinx``. For example, this is the output for | ||
Sphinx itself: | ||
|
||
.. code-block:: console | ||
:emphasize-lines: 4 | ||
|
||
(.venv) $ python -msphinx.ext.intersphinx https://www.sphinx-doc.org/en/master/objects.inv | grep 'std:doc' --after-context 5 | ||
std:doc | ||
changes Changelog : changes.html | ||
contents Sphinx documentation contents : contents.html | ||
development/builders Configuring builders : development/builders.html | ||
development/index Extending Sphinx : development/index.html | ||
development/overview Developing extensions overview : development/overview.html | ||
|
||
To link your documentation with the Sphinx one, add a | ||
:confval:`intersphinx_mapping` dictionary to your ``conf.py`` as follows: | ||
|
||
.. code-block:: python | ||
:caption: docs/source/conf.py | ||
|
||
intersphinx_mapping = { | ||
'sphinx': ('https://www.sphinx-doc.org/en/master/', None), | ||
} | ||
|
||
You can now introduce a cross-reference to the ``contents`` section of the | ||
Sphinx documentation as follows, optionally prefixing it by ``sphinx:``, the | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This prefixing is a bit of an icky issue. It doesn't work in general for all roles (and fundamentally can't), so in the end this should illustrate the feature with the role introduced by #9062. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I was not aware of that pull request. Do we want to introduce it even if it's not merged yet? Also, out of curiosity, can you expand a bit (or give an example) that doesn't work? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The tutorial should definitely be in sync with the implementation, so it's more that we should be aware of updating this part when relevant. Though, I guess this part will be merged after 4.1 (going out this weekend I believe), so there is a chance of the PR being ready in the same release as this. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As I commented above, one of the goal of intersphinx is transparency. So I prefer not to use prefix for cross references. As you explained, it is "optional" feature. So it would be better to explain the extension by non-prefixed example at first, I think. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fair enough, it looked more clar to me that way, but I'm +1 on explaning the fully consistent and transparent way instead. Will rephrase this part. |
||
key you used in the ``intersphinx_mapping`` configuration: | ||
|
||
.. code-block:: rst | ||
:caption: docs/source/index.rst | ||
|
||
.. note:: | ||
|
||
This documentation is built on Sphinx, | ||
:doc:`find out more in their docs <sphinx:contents>`. | ||
|
||
After you build the HTML documentation with ``make html``, you will see a link | ||
pointing to that specific page of the Sphinx documentation! | ||
|
||
Where to go from here | ||
--------------------- | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The goal of the Intersphinx extension is referring to remote objects transparently like referring to local objects. We've usually found local objects via reading source documents, I believe. So I think the way to find the remote objects is also reading source documents, first. Is searching
objects.inv
really better way to do that? I don't think so...This tutorial does not describe the relationship between the
std:doc
and:doc:
role. Where they came from? I'm worried this explanation makes beginners confused.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was only to explain what the file is. Perhaps it is too technical? I find myself using this quite often lately, perhaps because I'm still learning the intricacies of intersphinx. @webknjaz has https://webknjaz.github.io/intersphinx-untangled/ and I think it's quite useful too.
In any case, I can clarify that this is optional and that it works in the same way as your own docs (except for custom roles, like Sphinx own
:confval:
.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It doesn't because I need to learn it myself...!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I had no luck on the Sphinx docs but I found this somewhere else:
Now I understand your point. I will think if I can clarify this earlier, otherwise rephrase this part.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd love to see this table in the official docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've never had to do this by reading the source — it's hard to locate such things when you don't know where they are defined and how. Besides, the source is not always linked or available.
This is why I came up with intersphinx-untangled — it helps me discover things that are actually available. I sometimes even search by URL to see what roles link there.
I think there should be some sort of a reference explorer (I mentioned this somewhere on the tracker earlier).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep: #8211
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes. Some kinds of objects (including labels and documents) belong to the std domain. It behaves like a system domain. So users do not need to give the domain name on referencing objects like
:std:doc
or:std:ref:
.https://github.com/sphinx-doc/sphinx/blob/4.x/sphinx/domains/std.py#L562-L570
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've never thought referencing remote document via intersphinx. So I did not know such a behavior. Indeed, it would be a bug.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for chiming in @tk0miya ! I opened a discussion on https://groups.google.com/g/sphinx-dev/c/ZfslSpDGNUs/m/RjfzzFzUCgAJ about it, I think it's somewhat addressed by #9459