Guide: Intersphinx in Read the Docs #6520
Conversation
| If you are using :doc:`/commercial/index`, | ||
| Intersphinx will not be able to fetch the inventory file from private docs. | ||
|
|
||
| Intersphinx supports `URLs with Basic Authorization <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#using-intersphinx-with-inventory-file-under-basic-authorization>`__, |
There was a problem hiding this comment.
sphinx doesn't have a link to this section (actually I added that section 😁) and they don't use the autosectionlabel extension :(
There was a problem hiding this comment.
There's a lot of pages and sections in the Sphinx docs that can't be linked to with Intersphinx sadly.
|
|
||
| .. note:: | ||
|
|
||
| Another way of using Intersphinx with private projects is to download the inventory file and keep it in sync when the project changes. |
There was a problem hiding this comment.
I'm about to put this as another paragraph and not inside a note, not sure
| If you are using :doc:`/commercial/index`, | ||
| Intersphinx will not be able to fetch the inventory file from private docs. | ||
|
|
||
| Intersphinx supports `URLs with Basic Authorization <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#using-intersphinx-with-inventory-file-under-basic-authorization>`__, |
There was a problem hiding this comment.
There's a lot of pages and sections in the Sphinx docs that can't be linked to with Intersphinx sadly.
| - :ref:`sphinx:ref-role` | ||
| - :ref:`:ref: role <sphinx:ref-role>` | ||
| - :doc:`sphinx:usage/extensions/intersphinx` | ||
| - :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>` |
There was a problem hiding this comment.
This section is great and I love the example and result. Should we have a brief bit on how to get the target docs cross-references (eg. python -msphinx.ext.intersphinx https://...?) That is a bit technical and maybe linking to the Intersphinx docs is good enough until we build some explorer for it.
There was a problem hiding this comment.
Done! I also wanted to add a recommendation of using the autosectionlabel extension to make it easy to link to all headers without having to create targets manually, not sure if it fits in this guide.
Co-Authored-By: David Fischer <[email protected]>
|
Thanks for the review @davidfischer! I have moved the mention of |
|
|
||
| sphinx-build -b linkcheck . _build/linkcheck | ||
|
|
||
| See all the `options for the linkcheck builder <https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder>`__. |
There was a problem hiding this comment.
A perfect example of something that can't be linked to with Intersphinx.
docs/guides/intersphinx.rst
Outdated
|
|
||
| Some times you may need to link to a location of another documentation project. | ||
| We could just link to where the documentation is hosted. | ||
|
|
There was a problem hiding this comment.
I would remove the small paragraph above and combine it into the paragraph below. Something like:
Sometimes you may need to link to a specific section of another project's documentation.
While you could just hyperlink directly, there is a better way.
|
Failure on rtd is unrelated. |
This guide is about how to use intersphinx in general and how to use it in rtd (subprojects, translations, etc) and also with private projects in the commercial site.