Sphinx

08 Apr 2022

Sphinx

Installation in Ubuntu

via pip (recommended)

pip install -U sphinx

via conda

conda install sphinx

Quick Start

mkdir docs
cd docs

sphinx-quickstart

> Separate source and build directories (y/n) [n]:

> Project name:

> Author name(s):

> Project release []:

> Project language [en]:

build dir, source dir, make.abt file, Makefile created in docs dir

Install extensions

MyST parser

pip install myst-parser

Markdown Checkbox

pip install sphinx-markdown-checkbox

Copy button

pip install sphinx-copybutton

Copy button

pip install sphinx-design

Inline tabs

pip install sphinx_inline_tabs

select themes from here

> pip install furo:

autodoc

If it wasn’t commented out, it would indicate that your package is in the same directory as the conf.py file. You’ll need to change it to this:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

The Napoleon extension enables Sphinx to understand docstrings written in two other popular formats: NumPy and Google.

> extensions = [..,
'sphinx.ext.autodoc', 
'sphinx.ext.coverage', 
'sphinx.ext.napoleon'
]

sphinx-apidoc -o <OUTPUT_PATH> <MODULE_PATH>