Welcome to SphinxTest’s documentation!¶

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

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.

Docstring Format¶

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

It was very gross.
For everyone.

Solution¶

Google defined a non-gross docstring format that everyone accepts and Sphinx recognizes.

Sphinx needs an addon called “Napoleon” to interpret it.
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
]

alpha module¶

class alpha.Foo(barPower)[source]¶

Bases: object

This is the Foo class.

Create powerful Foo objects for generating foobars

power(int)¶: Amount of bar energy contained in this Foo instance.

Parameters:	barPower (int) – The bar energy to be contained in this Foo instance.
Raises:	`AssertError` – If barPower is less than 6, crap itself.

Examples

>>> from test import Foo
>>> x = Foo(6)
>>> x.bar()
>>> foobar0
>>> foobar1
>>> foobar2
>>> foobar3
>>> foobar4
>>> foobar5

bar()[source]¶: Generate foobars based on bar energy.

beta module¶

class beta.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

>>> Waldo([2,3,5])
>>> Waldo.whereIsHe()
>>> [2,3,5]