Sphinx + reStructuredText: Getting Started¶

Sphinx is a powerful documentation generator, and reStructuredText (reST) is its markup language of choice.

This page will help you get started using Sphinx with reST.

What You’ll learn¶

How to install Sphinx
Basic project structure
Creating and writing
Building your documentation

Installing Sphinx¶

Inside your project’s Python virtual environment, run:

pip install sphinx

Check that the install:

sphinx-quickstart --version

Basic Project structure¶

A typical Sphinx documentation project looks like:

docs/
├── build/          # Output files (HTML, PDF, etc.)
├── source/         # reST source files
│   ├── index.rst   # Main landing page
│   ├── conf.py     # Sphinx configuration file
│   └── usage.rst   # Example page
└── Makefile        # Build commands (e.g., make html)

Writing Your ‘.rst’ files¶

Use reStructuredText to create your pages:

Titles and Headings:
```
My Page Title
=============
```
Emphasis
- italic or bold
Links:

..code-block:: rst

Sphinx Docs

Building the Docs¶

From the docs directory, run:

make html

The HTML output will be in the docs/build/html/ folder. Open index.html in your browser!

Adding to `index.rst`¶

Update the .. toctree:: in your index.rst like this:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   usage
   api
   sphinx-getting-started