Install Sphinx for Python Documentation

Sphinx is a powerful tool for generating Python documentation. It converts reStructuredText files into HTML, PDF, and other formats. This guide will help you install and set it up.

Why Use Sphinx?

Sphinx makes it easy to create professional documentation. It supports auto-generating docs from docstrings. It also works well with version control.

Many Python projects use Sphinx, including CPython and Django. It is the standard for Python documentation.

Prerequisites

Before installing Sphinx, ensure you have Python installed. You can check this by running:

python --version

If Python is not installed, download it from the official website. You may also need pytest-cov for testing.

Install Sphinx

Use pip to install Sphinx. Run the following command in your terminal:

pip install sphinx

This will install Sphinx and its dependencies. Verify the installation with:

sphinx-build --version

Set Up a Documentation Project

Create a new directory for your docs. Navigate to it and run:

sphinx-quickstart

This command will guide you through setup. Answer the prompts to configure your project.

For example, you can set the project name and version. You can also enable autodoc to extract docstrings.

Configure conf.py

The conf.py file controls Sphinx settings. Open it and add the following if needed:

# Enable autodoc
extensions = ['sphinx.ext.autodoc']

This allows Sphinx to generate docs from docstrings. You can also add other extensions like Pexpect for automation.

Write Documentation

Create .rst files in the source directory. Use reStructuredText syntax to write your docs.

For example, create index.rst as the main page. Add modules and functions using autodoc directives.

.. automodule:: mymodule
   :members:

Build the Documentation

Run the following command to generate HTML docs:

sphinx-build -b html sourcedir builddir

Replace sourcedir with your source directory. Replace builddir with your output directory.

The docs will be generated in the build directory. Open index.html to view them.

Automate with Makefile

Sphinx generates a Makefile for automation. Use it to build docs quickly.

make html

This command rebuilds the HTML docs. You can also generate PDFs with make latexpdf.

Hosting Documentation

You can host your docs on Read the Docs. It supports Sphinx and updates automatically.

Alternatively, use GitHub Pages. Push the built HTML files to a gh-pages branch.

Conclusion

Sphinx is a great tool for Python documentation. It is easy to set up and use. Follow this guide to create professional docs.

For more advanced setups, check out PsySH or RPy2.