Skip to main content
Sphinx is a documentation generator widely used for Python projects. It converts reStructuredText files into various output formats including HTML and PDF, and is highly extensible via plugins and themes.
1
Install Sphinx
2
Sphinx can be installed via pip, conda, or uv. This guide uses uv:
3
uv init --bare
uv add sphinx

# Verify the installation
uv run sphinx-build --version
4
Create a New Sphinx Project
5
The sphinx-quickstart command walks you through the initial setup, creating a source directory and a default conf.py.
6
uv run sphinx-quickstart
7
Sample interactive output:
8
Welcome to the Sphinx 8.2.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n

The project name will occur in several places in the built documentation.
> Project name: sphinx-tutorial
> Author name(s): karchunt
> Project release []:
> Project language [en]:

Creating file conf.py.
Creating file index.rst.
Creating file Makefile.
Creating file make.bat.

Finished: An initial directory structure has been created.
9
Build a Live Documentation Preview
10
sphinx-autobuild rebuilds your docs and refreshes the browser automatically whenever source files change.
11
uv add sphinx-autobuild
uv run sphinx-autobuild ./ output
12
Sample output:
13
[sphinx-autobuild] Starting initial build
[sphinx-autobuild] > python -m sphinx build ./ output
Running Sphinx v8.2.3
build succeeded.

The HTML pages are in output.
[sphinx-autobuild] Serving on http://127.0.0.1:8000
[sphinx-autobuild] Waiting to detect changes...
14
Open your browser and navigate to http://127.0.0.1:8000.
15
Document Your Project
16
Edit index.rst and add additional .rst files as needed. Below are examples of the three common files:
17
index.rst
Welcome to KarChunT's documentation!
====================================

This is just a demo documentation by using **Sphinx**. Here is the `Reference <https://www.sphinx-doc.org/en/master/>`_ to Sphinx official website.

.. note::

  This project is under testing, so the content is very limited.

  Check out the :doc:`docs/usage` section for further information, including how to :ref:`install <installation>` the project.

  For API documentation and code examples, see the :doc:`docs/code` section.

Contents
--------

.. toctree::
  docs/usage
  docs/code
docs/usage.rst
Usage
=====

.. _installation:

Installation
------------

To use Lumache, first install it using pip:

.. code-block:: console

  (.venv) $ pip install lumache
docs/code.rst
Code
====

To document Python objects, use the ``py:function`` directive:

.. py:function:: add_numbers(a, b)

    Adds two numbers and returns the result.

    :param a: The first number.
    :param b: The second number.
    :type a: int or float
    :type b: int or float
    :return: The sum of the two numbers.
    :rtype: int or float
    :raises TypeError: If either a or b is not a number.

Cross-reference the function elsewhere with the ``:py:func:`` role:

You can use the :py:func:`add_numbers` function to add two numbers together.
18
(Optional) Customize the Theme
19
Sphinx ships with several built-in themes and supports third-party themes. The popular Read the Docs theme is a common choice.
20
uv add sphinx_rtd_theme
21
Update conf.py to activate it:
22
extensions = [
    # ... other extensions
    'sphinx_rtd_theme',
]

html_theme = "sphinx_rtd_theme"
23
Build the Documentation
24
Once your content is ready, build to your target format:
25
# Using sphinx-build directly
uv run sphinx-build -M html ./ output

# Using the Makefile (Linux/macOS)
make html

# Using the Makefile (Windows)
./make.bat html
26
Replace html with any supported builder name (e.g. latex, linkcheck). See the Sphinx builders list for all options.
27
After building, you can host the output on GitHub Pages, Read the Docs, or your own web server. Refer to the official Sphinx deployment guide for details.

Build docs developers (and LLMs) love

Get started for freeTalk to us