Template documentation

This repository contains a template for Read The Docs style auto documentation generation using Sphinx.

Usage

Copy and paste docs directory and .github/workflows/pages.yaml file. docs directory contains necessary minimum confiuration files for Sphinx builder. The github pages workflow automatically updates the webpage after a push to the master or the main branch. Include the contents of the .gitignore file in your own .gitignore file.

Note

Make sure not to copy LICENSE and README.md files since license and readme for the documented project high likely to be different.

Populating and the documentation

Installation

Sphinx is a Python based documentation generator. This template requires packages described in the docs/requirements.txt to be installed.

First install python3 and pip command line python package installer if ther are not installed already.

sudo apt install python3 python3-pip

Note

In some cases it maybe preferable to install python3 using sudo apt install python-is-python3.

Install required packages

pip install -r ./docs/requirements.txt

Building

Navigate inside the docs directory and execute the command below.

cd docs
sphinx-build -b html . _build

Note

Check your .gitignore file and make sure _build directory is ignored. When the repository is pushed to github, sphinx builder will be executed on the server.

You have several options to test out the generated documentation. First, you may just navigate into _build directory and open it with your favorite internet browser. Second, you may run a simple http server via python -m http.server 8080 -d docs/_build and explore it by visiting http://localhost:8080.

Deployment

For more information, read Github’s take on github pages.

  1. Visit the repository on github.

  2. Navigate to the repository settings. img

  3. In the “Code and automation” section of the sidebar, click Pages.Find “Pages” on the left navigation panel.

  4. Under “Build and deployment”, under “Source”, select Deploy from a branch.

  5. Select gh-pages branch.

  6. It should be all set. The documentation will be hosted at https://<organization_name>.github.io/<repository_name>

Note

The is a way to use custom URLs. If you are interested in it, please refer to github’s take on that issue.

Documentation Syntax

You can add as much as readme files inside the docs/index.md file. The files can be .md or .rst. If you plan to use .md files, sphinx special syntax documentation is hosted at MyST documentation.