Introduction

In this tutorial, I will create a documentation project on Read the Docs by importing a Sphinx project from a GitHub repository and exploring several useful features of the platform. The tutorial is aimed at people interested in learning how to use Read the Docs to host their documentation projects.

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.

Project tutorial

I will create a documentation project on Read the Docs with Sphinx and Markdown. The only things you will need to follow me are a web browser, an Internet connection and a GitHub account.

Getting started

First, make a directory on your pc (I have created a directory named read-the-doc) and navigate to the directory. In the second step it's better to create a virtual environment and upgrade pip as with the below commands:

python3 -m venv venv

python3 -m pip install -U pip

Now the project is ready to proceed to the next step to install our dependencies.

Installing Sphinx

Sphinx is a powerful documentation generator that has many great features for writing technical documentation including:

• Generate web pages, printable PDFs, and documents for e-readers (ePub)
• You can use reStructuredText or Markdown to write documentation
• Syntax highlighted code samples

Assuming you have Python already, install Sphinx:

pip install sphinx

Create a directory inside your project to hold your documentation:

mkdir docs

Run sphinx-quickstart in the docs directory:

cd docs
sphinx-quickstart

or

sphinx-quickstart docs

This quick start will walk you through creating the basic configuration; in most cases, you can just accept the defaults. When it’s done, you’ll have an index.rst, conf.py and some other files in your docs directory.

Markdown with Sphinx

You can use Markdown using MyST in the Sphinx project.

RST-to-MyST

A tool for converting ReStructuredText to MyST Markdown. this tool convert the .rst file into .md extension.

To install from PyPI:

pip install "rst-to-myst[sphinx]"

Basic conversion command of a whole project:

rst2myst convert docs/**/*.rst

The above command has converted the index.rst into an index.md, now delete index.rst from your project.

Myst-Parser

To get started with the MyST parser extension, with a focus on enabling it in the Sphinx documentation engine.

To install use pip:

pip install myst-parser

To use the MyST parser in Sphinx, simply add the following to your conf.py file:

extensions = ["myst_parser"]

This will activate the MyST Parser extension, causing all documents with the .md extension to be parsed as MyST.

Now, edit your index.md file and add some information about your project.

Add the below line to include README.md file:

Add warning for the project:

Update your toctree:

Add ref/link as below:

Build them to see how they look:

make html

Your index.md has been built into index.html in your documentation output directory (build/html/index.html). Open the index.html file in your web browser to see your docs.

Import Project on Read the Docs

At this stage, my test project is ready to upload on Github.com, furthermore, import on Read the Docs.

Preparing your project on GitHub

In the command line, navigate to the root directory of your project.

• Initialize the local directory as a Git repository.

git init -b main

• Stage and commit all the files in your project.

git add . && git commit -m "initial commit"

• Create a new repository on GitHub.com. To avoid errors, do not initialize the new repository with README, license, or gitignore files. You can add these files after your project has been pushed to GitHub.

• Push the changes in your local repository to GitHub.com.

Sign up for Read the Docs

To sign up for a Read the Docs account, navigate to the Sign Up page and choose the option Sign up with GitHub. On the authorization page, click the green Authorize readthedocs button.

After that, you will be redirected to Read the Docs, where you will need to confirm your e-mail and username. You created your account on Read the Docs and are ready to import your first project.

To upload the project see Importing the project on the website.

After uploading the project your build will fail, navigate to your GitHub repository, and add a .readthedocs.yaml file with these contents to the root of your project:

version: 2

build:
  os: "ubuntu-20.04"
  tools:
    python: "3.8"
sphinx:
  configuration: docs/source/conf.py    

python:
  # Install our python package before building the docs
  install:
    - requirements: requirements.txt

formats:
  - pdf
  - epub

Create requirements.txt file with the below contents to the root of your project:

myst-parser==0.18.1
Sphinx==4.5.0

After you commit these changes, go back to your project home, wait for the build process to complete, the project is done, and enjoy.