6.1 Installation

Installation on Linux

Warning

Python is also used by the Linux kernel, take care of how you update the default one

Setup Python virtual environment

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

To install a Python package we will use

# Install a Python package
pip install sphinx

But for this case, we will run

# Install all dependencies
pip install -r requirements.txt

Getting started

To create a quickstart documentation we will run:

# Create a quickstart documentation
sphinx-quickstart

Install Read-the-docs theme

# Install Read-the-docs theme
pip install sphinx-rtd-theme

Added code in your `conf.py` file

import sphinx_rtd_theme

extensions = [
      'sphinx_rtd_theme',
]

html_theme = "sphinx_rtd_theme"

Build documentation

Note

If you don’t have to make installed it, you can install it.

sudo apt install make

Then run (you should run this command from the root of the project)

make html

Note

Complete documentation: https://www.sphinx-doc.org/en/master/index.html

What are all these files

File structure

Your file system should now look similar to this

docs-as-code
├── build
└── source
├── index.rst
    ├── conf.py
    ├── _build
    ├── _static
    ├── _templates
├── venv
├── .gitignore
├── Makefile
├── make.bat
└── requirements.txt

We have a top-level docs directory in the main project directory. Inside this is:

index.rst:

This is the index file for the documentation, or what lives at /. It normally contains a Table of Contents that will link to all other pages of the documentation.

conf.py:

Allows for customization of Sphinx. You would not need to use this too much yet, but it is good to be familiar with this file.

Makefile & make.bat:

This is the main interface for local development, and should not be changed.

_build:

The directory that your output files go into.

_static:

The directory includes all your static files, like images.

_templates:

Allows you to override Sphinx templates to customize the look and feel.

venv:

The Python virtual environment where we will install all dependencies.

requirements.txt

The Python requirements needed to install sphinx.

.gitignore

A special file is interpreted by git and will ignore adding files or directories.

.nojekyll

A special file interpreted by GitHub will allow us to push our site.