RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html below:

Website Navigation

Read the Docs user documentation

Sphinx — Read the Docs user documentation

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 sphinx command, and defining the location of the installation requirements:

 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 following optional configuration changes to your Sphinx 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:

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:

// Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
// NOTE: The selector of the search input may need to be adjusted based on your theme.
document.querySelector("[role='search'] input").addEventListener("focusin", () => {
   const event = new CustomEvent("readthedocs-search-show");
   document.dispatchEvent(event);
});

Include it in your build:

 html_js_files = [
     ("readthedocs.js", {"defer": "defer"}),
 ]

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 it locally by installing 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