Welcome to SphinxTest’s documentation!

The index.rst file

This file is located within the docs root and creates the table of contents (TOC) for displaying next to the page.

.
├── _build
│ └── html
├── _static
│ ├── aboutindex.rst
│ ├── introduction.rst
│ └── numpydocstrings.rst
├── _templates
├── conf.py
├── index.rst <— the index file
├── make.bat
└── Makefile

index.rst

While not mandatory, this helps with navigation quite a bit.

Unfortunately, the index.rst is much more difficult to automate as it is the basic source file of Sphinx.

If a new modules is created, its path needs to be written down in the index.rst file for it to show up in the TOC.

Getting Started with this test

Sphinx is made with reStructured text. It is a bit different than markdown.

  • This is some wild stuff right here.
  • directives use “:”
  • it is quite annoying to get used to

Some math

\[\frac{ \sum_{t=0}^{N}f(t,k) }{N}\]

That was some math. I bet it looks cool. Every tool I have for previewing this sucks.

Using markdown

Markdown may be used at the cost of some advanced functionalities

Blog post of some nerd ranting about it

Main points:

  • Markdown has no set standard

    • There are a million interpreters with millions of syntax

  • Harder to expand

    • May rely on CSS stuff
    • Breaks portability for other tools

Basically,

reStructured text is awful to write but is more stable and standard for documentation

Docstring Format

Back in the day, docstrings used to be just plain reStructuredText inside of docstrings.

  • It was very gross.
  • For everyone.

Solution

Numpy Project and Google defined a non-gross docstring formats that everyone accepts and Sphinx recognizes.

  • Sphinx needs an addon called “Napoleon” to interpret them.
  • It is not a problem. This is defined in the doc’s conf.py.

Numpy docstrings Example

conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.napoleon', # <- Here is Napoleon
]

See also: Google docstrings Example

The code in sphinxtest.alpha and sphinxtest.beta utilize this Docstring format and are automatically generated.

Testing the Code

The Foo is an extremely powerful class. The number of bar power defined by its power, which is a int.

alpha The alpha __init__ docstr

sphinxtest package

Subpackages

sphinxtest.beta package

Module contents
The __init__ docstr
class Waldo(pos)[source]

Bases: object

This is the Waldo class

Parameters:
  • pos ((Tuple(int,int,int)):) – Waldo’s current position
  • pos – Start Waldo in this position
whereIsHe()[source]

Show Waldo’s Position

Returns:3 dimension coordinate of Waldo’s position
Return type:list

Example

>>> from sphinxtest.beta import Waldo
>>> w=Waldo([2,3,5])
>>> w.whereIsHe()
[2,3,5]

Module contents

Top level doctstring

Indices and tables