<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 ```bash $ 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/`) ```bash $ 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 ```sphinx .. 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 ```bash $ 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 ```bash $ 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 ```bash $ 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: ```bash $ 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: ```bash $ 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` ---