Skip to main content

Sphinx + Read the Docs

Here is a quick overview of a simple Sphinx + Read the Docs integration that was used to compile the High Fidelity user documentation.

info

Note: This article reflects the tools as they existed at the time of writing; functionality may have since changed.

Overview​

For our main documentation system, we use Sphinx to generate it, and Read the Docs to publish/host it. GitHub is a helpful middleman and stores all of the docs.

Sphinx is an open-source, robust solution for software documentation that includes features that writers expect, like:

  • Single Source Publishing (HTML, PDF, ePub, and more)
  • Content reuse through includes
  • Multiple mature HTML themes that provide great user experience on mobile and desktop
  • Referencing across pages, documents, and projects
  • Index and Glossary support
  • Localization support

Read the Docs is a hosting platform for Sphinx-generated documentation. It takes the power of Sphinx and adds version control, full-text search, and other useful features. It pulls down code and doc files from Git then builds and hosts the documentation.

Install Sphinx for Local Builds​

We encourage you to compile the documentation locally on your computer prior to submitting a PR. To install Sphinx and its prerequisites:

  1. Run cmd as administrator.
  2. Install Chocolatey via the cmd (on one line): 
    @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
  3. Install Python 3 via Chocolatey via the cmd: 
    choco install python
  4. Restart cmd or refresh with the command: 
    refreshenv
  5. Install Sphinx in a command line: 
    pip install -U sphinx
  6. Install the Markdown parser recommonmark: 
    pip install --upgrade recommonmark
  7. Install our Sphinx theme: 
    pip install sphinx_rtd_theme

Compile Documentation Locally​

  1. Fork and clone your documentation Git repository.
  2. Using a command line, cd to your local repository, then the docs folder.
  3. Compile with the command make html.

The HTML output will be in build\html. Open index.html in a browser to view the docs.

Running a Build Using Read the Docs​

The Read the Docs project is configured to be triggered by changes to the documentation Git repository. When you push a PR, Read the Docs automatically performs the following steps:

  • Creates a Docker container to run build process
  • Checks out code from the main branch
  • Installs runtime dependencies
  • Creates a Python environment where all dependencies will be installed
  • Installs Sphinx and project dependencies
  • Builds the documentation
  • Uploads the resulting website to the hosting servers

Versions of the documentation are managed through branches in the Git repository. To create a new version, create a new branch with the version number (i.e. V10). The project is configured to automatically build each version when you push a commit.

Using RST​

Most of our docs use RST. reStructuredText (RST) is the default plaintext markup language used by Sphinx. It is an extensible markup language, that is fully customizable. However, we don't (yet) have need of this, and will stick with the default set of directives for High Fidelity's documentation. To learn more, refer to Sphinx's reStructuredText Primer.

Back to Portfolio