Sphinx Directives and Roles¶

Everything in the reStructuredText section before, is built-in features of reStructuredText. Those can be parsed by Docutils without needing Sphinx.

In this section, we’ll learn about the Sphinx-specific roles and directive.

You will need to have Sphinx for these to work.

Cross-referencing¶

One of the Sphinx features that I appreciate the most is the ability to do cross-referencing, which is being able to provide links from one page of documentation to another page.

For example, suppose I have an installation guide within my documentation. From other pages of my documentation, I may want to easily refer to the installation guide. This is called “cross-referencing”.

Cross-referencing is accomplished by two elements: a target and the reference role.

First, declare a target or label, which works like a “bookmark”. And the syntax may look familiar to you by now; this is how you’d “name” your links.

In the documentation where I have my Installation Guide written, I’d add the following “target” or “label”.

.. _install-guide:

Installation Guide
==================

Step 1: Create and activate a virtual environment
Step 2: pip install it

Now, anywhere within my documentation, I can add :ref:`install-guide`. When the documentation is built, :ref:`install-guide` will be replaced with a link to the Installation Guide section of the documentation.

Cross-referencing documentation pages¶

Use the :doc: role to cross-reference another page, as opposed to a specific section, like what the :ref: role does.

:doc:`license`
:doc:`docs_in_python`
:doc:`Custom Docs title <docs_in_python>`

Will render the following links:

License

Documentation in Python Open Source Community

Custom Docs title

Downloadable Files¶

If you want to create a link to a downloadable content, i.e. things that cannot be viewed or rendered on the browser, like a zip file, you can use the :download: role.

Download :download:`this Makefile <../make.bat>`