changed 3 years ago
Linked with GitHub

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


What is documentation?

Documentation System

Image from Divio

Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →
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
  1. Edit your conf.py, index.rst and any other files you wish
  2. 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


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

$ 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


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

  1. 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
    
  2. Finally, we can build the documentation:

    ​​​$ make -C doc/ html
    
  3. Submit a Pull Request

    Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →


Jupyter notebooks


Final thoughts


Obrigada!
Image Not Showing Possible Reasons
  • The image file may be corrupted
  • The server hosting the image is unavailable
  • The image path is incorrect
  • The image format is not supported
Learn More →

@melissawm


Select a repo