Documentation for PiPico W training

Sphinx Logo

About

Sphinx generate documentation in the preferred formats of your audience, including HTML, LaTeX (for PDF), ePub, Texinfo, and more.

Sphinx workflow

Github workflow for creating Sphinx docs can be found here.

How to instructions…

Install Sphinx from PyPI package
Sphinx packages are published on the Python Package Index (PyPI). The preferred tool for installing packages from PyPI is pip, which is included in all modern versions of Python.

  1. Open CMD

  2. Run:

 python -m pip install -U sphinx
 python -m pip install sphinx_rtd_theme
 python -m pip install --upgrade myst-parser
 python -m pip install commonmark
 python -m pip install docutils
Check Sphinx version

  1. Open CMD

  2. Run:

sphinx-build --version
sphinx-quickstart --version
Check whether MyST parser is available

  1. Open CMD

  2. Run:

python -c "import myst_parser"
Defining document structure
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you.

  1. Open CMD:

  2. Run:

sphinx-quickstart
Sphinx build

  1. Open CMD

  2. Run:

sphinx-build docs docs/_build --verbose
Auto-Generated Python Documentation with Sphinx
Step by step:

  • Open CMD

  • Go to docs directory

  • Run:

make clean

  • Run:

sphinx-apidoc -F -P -o . ..

  • Add doc files name into relevant doc rst file

  • Run:

make html
Furo theme
A clean customisable Sphinx documentation theme.

Furo is distributed on PyPI. To use the theme in your Sphinx project:

  1. Install Furo in documentation’s build environment.

pip install furo

  1. Update the html_theme in conf.py.

html_theme = "furo"

  1. Your Sphinx documentation’s HTML pages will now be generated with this theme!

Source

Markdown support
To configure your Sphinx project for Markdown support, proceed as follows:

  1. Install the Markdown parser MyST-Parser:

pip install --upgrade myst-parser

  1. Add myst_parser to the list of configured extensions:

extensions = ['myst_parser']

  1. If you want to use Markdown files with extensions other than .md, adjust the source_suffix variable. The following example configures Sphinx to parse all files with the extensions .md and .txt as Markdown:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

  1. You can further configure MyST-Parser to allow custom syntax that standard CommonMark doesn’t support. Read more in the MyST-Parser documentation.

Source

Online Documentation

Detailed tech documentation is available here.

Source list