6.4. Sphinx

Select reference within AAAAAA

Reference	Topic
Sphinx	Conceptual explanation

Select references

Reference	Topic
Practical Sphinx presentation	Common usage
Project setup screencast	Start a project
Sphinx quickstart tutorial	Official tutorial

6.4.1. Building documentation

Builders enable you to create both website and PDF documentation styles. Make sure you are using a6 for the below procedures

6.4.1.1. Manually

Per Carol Willing’s Practical Sphinx talk from PyCon 2018:

1. Activate the a6 environment from inside the documentation root directory if it is not already active

2. From the VS Code integrated terminal, build the HTML for documentation then start a server

   make html
   python -m http.server
   

3. Open http://localhost:8000/_build/html/index.html in a web browser to view the website for documentation

4. You can update the .rst files and repeat the process, but don’t start another server (unless you want an HTTP socket error):

   make html
   

5. Refresh the browser to see changes

6. Before committing, clear out the build:

   make clean
   

Tip

You can automate this process if you want quick updates, like if you are proofreading documentation

6.4.1.2. Automatically

Select reference within AAAAAA

Reference	Topic
sphinx-autobuild	Conceptual explanation

Select reference

Reference	Topic
sphinx-autobuild	Official user manual

1. Like in the manual build procedure, use the a6 environment from inside the documentation root directory via the VS Code integrated terminal:

   sphinx-autobuild . _build/html -B -s 1
   

   sphinx-autobuild options:

   -B	Automatically open browser
   -s	Delay [1] before opening browser

   • This should automatically open a web browser
   • The server should be at http://127.0.0.1:8000

2. Use control-c to stop the server

3. Keep in mind:

   • Once the server is running, saved changes to any .rst files should cause your web browser to update whatever part of the website you are viewing
   • You will still need to manually navigate to the webpage you want to view
   • If your web browser is set to a URL that ends with .html, the webpage will refresh in the same vertical position, but you may not be granted this luxury if the URL ends with something like .html#a-heading-you-clicked-on
   • For some reason, at least on a Mac, you may need to quit your web browser, stop sphinx-autobuild via control-c and then re-do the above before the auto-refresh behavior will work

Footnotes

[1]	If you try to use no delay at all, -s 0, the browser might not open

6.4.1.3. PDF version

Note

Read the Docs will do this for you, but if you are so inclined it is possible to do it on your computer

1. Download based on your OS:

   OS	What to get
   Mac	MacTeX
   Windows	Tex Live
   Linux	Tex Live (probably)

2. Use the VS Code integrated terminal from inside the documentation root directory, with the LaTeX builder:

   make latex
   

3. Temporarily create a conda environment that you won’t need again

   conda create -n PDF perl
   

4. Activate the PDF environment, then navigate to _build/latex:

   make
   

   Tip

   You may need to do this a few times since it can take a few passes to resolve all the internal references. Just type enter if you get queried at all

6.4.2. Managing references

6.4.2.1. Using Intersphinx

Select reference within AAAAAA

Reference	topic
Intersphinx	Conceptual explanation

Select references

Reference	Topic
sphinx.ext.intersphinx	Official documentation
Intersphinx reference syntax	Syntax explanation
Intersphinx inventory parser	For linking to large projects

1. Locate the project’s objects.inv mapping, using the VS Code integrated terminal:

   python -msphinx.ext.intersphinx http://www.sphinx-doc.org/en/master/objects.inv
   

   • You may have to experiment with the project base URL. Some common endings:

     • org/en/master/
     • .io/en/latest/
     • .com/en/latest/

2. Add the project’s base URL to the intersphinx_mapping dictionary in conf.py:

   intersphinx_mapping = {
       'python': ('https://docs.python.org/3', None),
       'sphinx': ('http://www.sphinx-doc.org/en/master/', None),
       'pytest': ('https://docs.pytest.org/en/latest/', None),
       'rtfd': ('https://docs.readthedocs.io/en/latest/', None),
       'rtd-sphinx-theme':
           ('https://sphinx-rtd-theme.readthedocs.io/en/latest/', None),
       ...
   

3. Inspect the objects.inv mapping from the project in question

   • For large outputs, consider using a command line instead of the VS Code integrated terminal (but make sure to use a6)

4. Locate the desired target in the output and link to it using a corresponding role:

   Referencing select outputs

   Category in objects.inv	Role to use
   std:doc	:doc:
   rst:directive	:rst:dir:
   std:label	:ref:

5. Webpages of documentation, under std:doc, are arranged like the project’s table of contents, so you can figure out the role target from the URL that a browser displays for the particular webpage. Consider https://docs.python.org/3/tutorial/introduction.html:

   URL decomposition

   Portion	Interpretation	In role target
   https://docs.python.org/3/	Base URL	python:
   tutorial/introduction.html	Desired webpage	tutorial/introduction

6. You can optionally define your own role title:

   An Informal Introduction to Python

   :doc:`python:tutorial/introduction`
   

   A most beauteous tutorial

   :doc:`A most beauteous tutorial <python:tutorial/introduction>`
   

7. Add a description of the link to links

8. Add a role to documentation using the appropriate capitalization:

   Read about Sphinx roles

   Read about :doc:`Sphinx roles <sphinx:usage/restructuredtext/roles>`
   

Note

When possible, use :ref: instead of :doc:, because the project’s toctree may change

See also

Intersphinx with NumPy/Matplotlib has instructions for referencing NumPy and Matplotlib, though standard procedures from above are usually sufficient for AAAAAA

6.4.2.2. Referencing external links

For links that can not be managed with Intersphinx, use either xref or extlinks. In general you can use xref, but if the webpage you want to cite comes from a website that you often use, it makes sense to use extlinks:

1. Wikipedia articles, like https://en.wikipedia.org/wiki/Download:

   Resultant role

   :wiki-pg:`Download`
   

2. RealPython tutorials, like https://realpython.com/python-type-checking:

   Resultant role

   :real-py:`python-type-checking`
   

3. Even Stack Overflow questions, like https://stackoverflow.com/questions/1441010/the-shortest-possible-output-from-git-log-containing-author-and-date:

   Resultant role

   :stack-q:`https://stackoverflow.com/questions/1441010/the-shortest-possible\
   -output-from-git-log-containing-author-and-date
   <1441010/the-shortest-possible-output-from-git-log-containing-author-and-\
   date>`
   

   • Note that this works, but there may not be syntax highlighting in the above code-block because of the \-escapes for new lines
   • This is still in compliance with line breaking standards

6.4.2.2.1. xref

Select reference within AAAAAA

Reference	topic
xref	Conceptual explanation

Select reference

Reference	Topic
Sphinx xref extension	User manual

1. Add your URL to the xref_links dictionary in conf.py, below the delimeter-style comment that reads New links below, sorted links above

   xref_links = {
       'Python': ('Python', 'https://www.python.org'),
       ...
       'semver': ("Semantic Versioning", 'https://semver.org/'),
       # New links below, sorted links above
       'ottobib': ('OttoBib', 'https://www.ottobib.com'),
   }
   

2. Add a link role to .rst files using the appropriate capitalization and an optional role title:

   Python

   :xref:`Python`
   

   Python.org

   :xref:`Python.org <Python>`
   

3. Add a description of the URL to links

   • After this step, the URL can be moved above the delimiter-stye comment from conf.py

Optimality considerations

• As long as URLs aren’t put above the delimiter-stye comment until after they are put into links, URLs can be sorted in reasonably sized batches
• If you put a link in .rst files and in links first, you can bypass the delimiter-stye comment altogether when adding to conf.py

6.4.2.2.2. extlinks

Select reference within AAAAAA

Reference	topic
extlinks	Conceptual explanation

Select references

Reference	Topic
extlinks	Official documentation
Using a references extension	Related configuration and usage

1. Add your base URL to the extlinks dictionary in conf.py, with a %s at the end:

   extlinks = {
       'wiki-pg': ('https://en.wikipedia.org/wiki/%s', ''),
       'real-py': ('https://realpython.com/%s', ''),
       ...
   }
   

2. After you have added the base URL, you will then have access to a new custom role:

   Yields Internet

   :wiki-pg:`Internet`
   

   Yields download

   :wiki-pg:`download <Download>`
   

   Note

   The link checker is particular about capitalization for Wikipedia, so make sure to use the exact string from the end of the URL: Download, not download

3. For most websites other than Wikipedia, you will usually want to add in a role title:

   Yields python-type-checking

   :real-py:`python-type-checking`
   

   Yields type checking guide

   :real-py:`type checking guide <python-type-checking>`
   

4. Add a description of the URL to links, then add your custom role to documentation using the appropriate capitalization

Tip

Although you could use extlinks to create a URL that is not actually associated with a webpage, the link checking procedure will identify such errors

6.4.2.3. Checking links

Per Carol Willing’s Practical Sphinx talk from PyCon 2018:

1. From inside the documentation root directory, use the VS Code integrated terminal:

   make linkcheck
   

6.4.2.4. Updating labels

1. With an active build running, open the VS Code integrated terminal from inside the documentation root directory

2. Use Intersphinx on _build/html/objects.inv to inspect inspect labels for AAAAAA

3. Verify the proper label style

4. Update any labels via the VS Code Command Palette

   • Search: Replace in Files

6.4.2.5. Referencing books

Select references within AAAAAA

Reference	Topic
BibTeX	Conceptual explanation
refs.bib	Collection of BibTeX-style citations

Select references

Reference	Topic
Book	Information source
BibTeX	Citation format
BibTeX extension	Converts BibTeX
OttoBib	Get BibTeX for your book
ISBN	Unique identifier for books
BibTeX Entry and Field Types	Syntax specifications
Convention for citing multiple authors	Use of et. al

1. Check OttoBib for your ISBN and copy-paste the BibTeX option into refs.bib

2. Verify that you added a book entry in refs.bib

   • A book entry requires at least author (or editor), title, publisher, and year fields
   • Consider et. al conventions for multiple authors

3. Add a role to books via :cite:`bib-book-name`

   • Use a heading so that toctree can index the entry
   • Use a label that starts with book- in books, and with bib- in refs.bib

   .. _book-on-managing-yourself:
   
   
   ********************
   On Managing Yourself
   ********************
   
   .. csv-table:: :cite:`bib-on-managing-yourself`
      :align: center
      :header: Page(s), Topic
   

   @Book{bib-on-managing-yourself,
    author = {Clayton M. Christensen et. al},
    title = {HBR's 10 Must Reads: On Managing Yourself},
    publisher = {Harvard Business Review Press},
    year = {2010},
    address = {Boston, Massachusetts},
    isbn = {978-1-4221-5799-2}
    }
   

Tip

The BibTeX extension is unreceptive to role titles