First things first

Image by David Whittaker

What is documentation?

Image from Divio Link to NEP 44

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 (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, which are blocks of explicit markup which can have arguments, options and content

Example: index.rst

• We'll see concrete examples of this in the NumPy documentation, but you can check out a nice summary of reST syntax and a longer reST primer.

Auto-documenting a Python package

• Sphinx supports the inclusion of docstrings from your modules with an extension called autodoc.

• The conf.py file

• 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 allows you to add tests to your docstrings. You can then run

$ make doctest

• The sphinx.ext.intersphinx 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
• 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

A Pull Request to the NumPy documentation

https://numpy.org/contribute/

With thanks to Fatma Tarlaci!

In our Quickstart guide, 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

Most of the steps are described in this page of the NumPy documentation.

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 git@github.com: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. 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
   

7. Submit a Pull Request

Jupyter notebooks

• nbsphinx
• Jupyter-Book
• 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
• There are many other interesting extensions for Sphinx
  • Sphinx Gallery
  • Documenting MATLAB code
  • link to external Doxygen API documentation
• For your own project, you can use github pages or https://readthedocs.org/ to serve your documentation online
• The WriteTheDocs community has a lot of other resources that you can check out.

Obrigada!

@melissawm