Skip to content
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

Guide: Intersphinx in Read the Docs #6520

Merged
merged 4 commits into from Jan 14, 2020
Merged

Conversation

stsewd
Copy link
Member

@stsewd stsewd commented Jan 14, 2020

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.

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>`__,
Copy link
Member Author

@stsewd stsewd Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sphinx doesn't have a link to this section (actually I added that section 😁) and they don't use the autosectionlabel extension :(

Copy link
Contributor

@davidfischer davidfischer Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a lot of pages and sections in the Sphinx docs that can't be linked to with Intersphinx sadly.

docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
.. note::

Another way of using Intersphinx with private projects is to download the inventory file and keep it in sync when the project changes.
Copy link
Member Author

@stsewd stsewd Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm about to put this as another paragraph and not inside a note, not sure

@stsewd stsewd requested a review from Jan 14, 2020
Copy link
Contributor

@davidfischer davidfischer left a comment

Overall, this guide is a fantastic first step and something we can build on.

docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
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>`__,
Copy link
Contributor

@davidfischer davidfischer Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a lot of pages and sections in the Sphinx docs that can't be linked to with Intersphinx sadly.

docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
docs/guides/intersphinx.rst Outdated Show resolved Hide resolved
- :ref:`sphinx:ref-role`
- :ref:`:ref: role <sphinx:ref-role>`
- :doc:`sphinx:usage/extensions/intersphinx`
- :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>`
Copy link
Contributor

@davidfischer davidfischer Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@stsewd stsewd Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@stsewd
Copy link
Member Author

@stsewd stsewd commented Jan 14, 2020

Thanks for the review @davidfischer! I have moved the mention of linkcheck to a note and also mention how to get the targets used in Intersphinx.

@stsewd stsewd requested a review from davidfischer Jan 14, 2020
Copy link
Contributor

@davidfischer davidfischer left a comment

I made a few small suggestions but otherwise this is good to go, I think.


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>`__.
Copy link
Contributor

@davidfischer davidfischer Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A perfect example of something that can't be linked to with Intersphinx.


Some times you may need to link to a location of another documentation project.
We could just link to where the documentation is hosted.

Copy link
Contributor

@davidfischer davidfischer Jan 14, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@stsewd
Copy link
Member Author

@stsewd stsewd commented Jan 14, 2020

Failure on rtd is unrelated.

@stsewd stsewd merged commit d0de565 into readthedocs:master Jan 14, 2020
1 of 2 checks passed
@stsewd stsewd deleted the intersphinx-guide branch Jan 14, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants