---
title: Intro to Sphinx for Python Documentation
tags: talk
description: View the slide with "Slide Mode".
slideOptions:
transition: fade
theme: sky
---
<style>
body {
background: #ffffff;
background-color: #ffffff;
}
.reveal .slides {
font-size: 36px;
font-family: Palatino;
}
.reveal .slides h2 {
font-family: Palatino;
letter-spacing: 0.005em;
}
.reveal .slides h3 {
font-family: Palatino;
letter-spacing: 0.005em;
}
.reveal .slides h4 {
font-family: Palatino;
font-size: 48px;
letter-spacing: 0.005em;
}
.reveal pre {
display: block;
width: 80%;
}
.reveal pre code {
max-height: 500px;
font-size: 22px;
line-height: 24px;
}
ul {
font-size: 30px;
}
</style>

## Intro to Sphinx for Python Documentation

- slides: `https://hackmd.io/@melissawm/SkjCa3OkO#/`
- repo: `https://github.com/melissawm/minimalsphinx`
- docs: `https://numpy.org/doc/stable`

---

### First things first

*[Image by David Whittaker](https://twitter.com/rundavidrun/status/587671657193455616/photo/1)*

---

### What is documentation?


<!-- .slide: style="font-size: 28px;" -->
*Image from [Divio](https://documentation.divio.com/)* :small_blue_diamond: *[Link to NEP 44](https://numpy.org/neps/nep-0044-restructuring-numpy-docs.html)*

---

### What is Sphinx?

- Documentation generator
- It takes plain text source files and generates readable output, mainly HTML
- For our use case you can think of it as **a program that takes in plain text files in a special format called `reStructuredText`, and outputs HTML**.
- reST 🠲 Sphinx 🠲 HTML, PDF
- Sphinx needs a configuration file `conf.py`
- Extensible

---

### On an empty project

1. Install `sphinx` (for example, `pip install sphinx`)
2. Initiate the `conf.py` file and initial directory structure by running

$ sphinx-quickstart

3. Edit your `conf.py`, `index.rst` and any other files you wish
4. Build outputs (they can be found at `_build/html/`)

$ make html

---

### The reStructuredText format

- After running `sphinx-quickstart`, an `index.rst` file is created
- [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) (or reST) is a markup syntax
- Autogenerate documentation, including inline markup, custom content, powerful linking and referencing features.
- The standard reST inline markup consists of
- one asterisk: `*text*` for emphasis (italics),
- two asterisks: `**text**` for strong emphasis (boldface)
- backquotes: ``` ``text`` ``` for code samples.

---

### The reStructuredText format II

- reST also implements [directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives), which are blocks of explicit markup which can have arguments, options and content

[Example: index.rst](https://raw.githubusercontent.com/melissawm/minimalsphinx/main/docs/index.rst)

<!--
- `` `toctree` `` is a reStructuredText directive; `maxdepth` and `caption` are options for this directive, and their values are `2` and `Contents:`. In addition, you can see the `:ref:` *role* in this file. Sphinx implements [interpreted text roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html) to insert semantic markup into documents. For example, `:ref:`search`` implements the role `ref` with the content `search` - in this particular case, we are cross-referencing a location, in this case creating a link to the document with label `search`.
-->

- We'll see concrete examples of this in the NumPy documentation, but you can check out a [nice summary of reST syntax](https://sphinx-tutorial.readthedocs.io/step-1/) and a longer [reST primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html).

---

### Auto-documenting a Python package

- Sphinx supports the inclusion of docstrings from your modules with an extension called [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc).

- [The `conf.py` file](https://github.com/melissawm/minimalsphinx/blob/main/docs/conf.py)
- You can then document whole classes or even modules automatically, using member options for the auto directives, like

.. automodule:: io
   :members:

---

### Other extensions

- The [sphinx.ext.doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html) allows you to add tests *to your docstrings*. You can then run

$ make doctest

- The [sphinx.ext.intersphinx](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) extension allows you to refer to other project's documentation labels easily by using their *intersphinx mapping*. (We'll see a concrete example later)

---

### Example: NumPy docs

- [How to contribute to NumPy documentation](https://numpy.org/devdocs/dev/howto-docs.html)
- Documentation team
- Don't worry if english is not your first language
- Ideas:
- Open an issue requesting content that you think is missing
- Suggest tutorials
- Suggest video content
- Join our [communication channels](https://numpy.org/contribute)

---

#### A Pull Request to the NumPy documentation

<!-- .slide: style="font-size: 28px;" -->

https://numpy.org/contribute/

*With thanks to Fatma Tarlaci!*

In our [Quickstart guide](https://numpy.org/doc/stable/user/quickstart.html#quickstart-stacking-arrays), there is a typo in the following sentence:

In general, for arrays with more than two 
dimensions, hstack stacks along their second axes, 
vstack stacks along their first axes, and 
concatenate allows for **an** optional arguments 
giving the number of the axis along which the 
concatenation should happen.

We'll fix this now.

---

### Steps

<!-- .slide: style="font-size: 26px;" -->
Most of the steps are described [in this page of the NumPy documentation](https://numpy.org/doc/stable/dev/index.html).

1. Fork the NumPy repository using the GitHub web interface
2. Clone your own fork of the NumPy repository from GitHub and set the `upstream` remote

    $ git clone [e-mail]:melissawm/numpy.git
    $ git remote add upstream http://github.com/numpy/numpy.git

3. Go to the root folder of the cloned repo and checkout a branch for your fix

    $ git checkout -b doc_fix

4. *Do your fix*

---

5. Now we can [build NumPy](https://numpy.org/devdocs/user/building.html). Using pip+venv:

    $ virtualenv venv
    $ source venv/bin/activate
    $ pip install -r doc_requirements.txt
    $ pip install cython
    $ python setup.py build_ext -i -j4

6. Finally, we can build the documentation:

   $ make -C doc/ html

8. Submit a Pull Request :tada:

---

### Jupyter notebooks

- [nbsphinx](https://nbsphinx.readthedocs.io)
- [Jupyter-Book](https://jupyterbook.org/intro.html#under-the-hood-the-components-of-jupyter-book)
- [Numpy Tutorials](https://github.com/numpy/numpy-tutorials)

---

### Final thoughts

- Sphinx can be challenging. It may be a good idea to check other projects that already use Sphinx to understand how to do advanced tasks.
- If you prefer using only markdown, check out [MyST](https://myst-parser.readthedocs.io/en/latest/)
- There are [many other interesting extensions for Sphinx](https://github.com/sphinx-contrib/)
- [Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html)
- [Documenting MATLAB code](https://github.com/sphinx-contrib/matlabdomain)
- [link to external Doxygen API documentation](https://github.com/sphinx-contrib/doxylink)
- For your own project, you can use github pages or https://readthedocs.org/ to serve your documentation online
- The [WriteTheDocs](https://www.writethedocs.org/) community has a lot of other resources that you can check out.

---

### Obrigada! :heart:

## `@melissawm`

---