Sphinx
Sphinx is a powerful documentation generator tool that allows you to create high-quality documentation for your projects in various formats such as HTML, PDF, EPUB, and more. It is written in Python and is often used to document Python projects, although it can be used with other programming languages as well.
Sphinx uses reStructuredText as its markup language, which is easy to read and write and can be easily converted into other formats. It also supports a range of extensions that provide additional functionality, such as automatically generating documentation from code comments, cross-referencing between different parts of the documentation, and more.
Sphinx also has built-in support for internationalization, which allows you to easily create documentation in multiple languages. It provides a variety of themes that you can use to customize the look and feel of your documentation, and it integrates well with version control systems like Git and Subversion.
Folder structure
In the following, we assume that your python module lives in a folder src
. To clearly separate the source code from the documentation, create a docs
folder at the same level of your src
folder.
.
├── docs
├── src
│ │ __init__.py
│ └── core.py
...
Getting Started
In the docs
folder, run the following command
sphinx-quickstart
In the same folder, create a subfolder called /api
and add a file called api/index.rst
.
docs
Structure
Your docs
directory should have the following structure.
.
├── Makefile
├── _build
├── _static
├── _templates
├── api
│ └── index.rst
├── conf.py
├── index.rst
└── make.bat
Change the content of the index.rst
and api/index.rst
as follows.
Welcome to your documentation!
====================================
.. toctree::
:maxdepth: 2
:caption: Contents:
api/index
API
===
Build the documentation
The following command build an HTML version of the documentation.
make html
The documentation is then located in your _build/
directory. Simply open the file _build/html/index.html
with your browser.
Pydata theme
It if possible to change the theme of the documentation.
- Install the pydata theme
pip install pydata-sphinx-theme
- Change the html_theme variable in the
config.py
file as follows
...
html_theme = "pydata_sphinx_theme"
...
Auto Documentation
The sphinx.ext.autodoc
can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way.
Configuration file
To activate the sphinx.ext.autodoc
extension, change the following files as
import os # uncomment this line
import sys # uncomment this line
sys.path.insert(0, os.path.abspath('../src')) # where the source code lives
...
extensions = ['sphinx.ext.autodoc']
...
API
===
.. automodule:: src.core
:members:
def show_message(name):
"""show_message
print a message
:param name: str
"""
print("Hello {}".format(name))