Sphinx

Sphinx is a powerful documentation generator that has many features for writing technical documentation. Sphinx is written in Python, and supports documentation written in reStructuredText and Markdown.

Minimal configuration required to build an existing Sphinx project on Read the Docs looks like this, specifying a python 3.x toolchain on Ubuntu, using the built-in mkdocs command, and defining the location of the installation requirements:

.readthedocs.yaml

   version: 2

   build:
      os: ubuntu-24.04
      tools:
         python: "3"

   sphinx:
      configuration: docs/conf.py

   python:
      install:
         - requirements: requirements.txt

Quick start

If you have an existing Sphinx project you want to host on Read the Docs, check out our Adding a documentation project guide.
If you’re new to Sphinx, check out the official Getting started with Sphinx guide.
For a step by step tutorial on Read the Docs using an example Sphinx project, take a look at the Read the Docs tutorial.

Configuring Sphinx and Read the Docs addons

For optimal integration with Read the Docs, make the optional following configuration changes to your Spinx config.

Set the canonical URL

A canonical URL allows you to specify the preferred version of a web page to prevent duplicated content.

Set your html_baseurl to your Read the Docs canonical URL using a Read the Docs environment variable:

conf.py

html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")

Configure Read the Docs search

If you’re using the Read the Docs Sphinx Theme, Server side search already works out of the box.

If you’re using a different theme, enable Server side search:

Add a snippet of JavaScript:

readthedocs.js

// Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
document.querySelector("[role='search'] input").addEventListener("focusin", () => {
   const event = new CustomEvent("readthedocs-search-show");
   document.dispatchEvent(event);
});

Include it in your build:

conf.py

 html_js_files = [
     "readthedocs.js",
 ]

Using Markdown with Sphinx

You can use Markdown using MyST and reStructuredText in the same Sphinx project. We support this natively on Read the Docs, and you can also use locally by installing myst-parser:

pip install myst-parser

Then in your conf.py:

extensions = ["myst_parser"]

You can now continue writing your docs in .md files and it will work with Sphinx.

Example repository and demo

Example repository: https://github.com/readthedocs/test-builds/tree/full-feature
Demo: https://test-builds.readthedocs.io/en/full-feature