How to cross reference links between package docs and signac docs using intersphinx

Here is an example of how to link from signac-docs to a package's docs. Don't hardcode links! If you hardcode links, it won't be obvious if the link breaks (Sphinx shows warnings for broken intersphinx references) and the hardcoded link will probably point to a version that is outdated.

This summarizes the Sphinx docs on Cross-referencing arbitrary locations, with a bit more explanation and examples specific to the signac project.

The Dashboard page in signac-docs has a reference :ref:`dashboard-security` : https://github.com/glotzerlab/signac-docs/blob/master/docs/source/dashboard.rst

This reference links to the label .. _dashboard-security: here: https://raw.githubusercontent.com/glotzerlab/signac-dashboard/master/doc/security.rst

When rendered, the reference is replaced by a link. The link text (and link target) are the section header below the reference label (Security Guidelines). Example: https://docs.signac.io/en/latest/dashboard.html

To create a new cross-reference, add a label like .. _unique-section-header-name above the heading for the desired link destination, and then add :ref:`unique-section-header-name` in signac-docs (or elsewhere in a package's documentation). The important part is to make sure that unique-section-header-name is a unique name and won't be used elsewhere. The more descriptive, the better. Ideally it matches the name of the (hopefully unique) section header.

This cross-referencing works because we have an intersphinx mapping from signac-docs to signac. It's also possible to link from signac-flow or signac-dashboard docs to signac docs, because they also have intersphinx mappings.

If you want to make sure that your cross-reference is interpreted in some intersphinx namespace, you can write it as namespace:crossreference like:

:ref:`This text links to jinja filters <jinja2:filters>`