Course Website with Sphinx#

Sphinx is a powerful documentation generator based on the reStructuredText markup language. It can be used to generate website in html or documentation in pdf from rst files. This tool is perfect to publish course content on the internet since it works well with latex, code, matplotlib figure, …

Getting Started#

Installation#

First, sphinx need to be installed on your system. Furthermore, I recommend to also install the pydata sphinx theme . This theme is super clean and it is used by many data science python librairies such as numpy, scipy and matplotlib.

$ conda install sphinx
$ pip install pydata-sphinx-theme

Creating a Documentation#

  • To create a documentation, run the following command :

$ sphinx-quickstart docs

Project Structure#

The sphinx-quickstart command creates a new folder docs and populates the folder with specific files.

  • Add the following files to your project

Makefile
build/
make.bat
requirements.txt    # add this
source/
    _ext/
    _static/
        custom.css  # add this
    conf.py
    courses/        # add this
        index.rst   # add this
        course1.rst # add this
    index.rst

File requirements.txt#

The requirements.txt file is important if you want to deploy your documentation automatically on github or collaborate with others. It specifies the python librairies used to build your doc.

  • Edit the requirements.txt file as below

Jinja2 < 3.1
pydata-sphinx-theme < 0.7.3
numpy   # if needed
scipy   # if needed
matplotlib  # if needed

File index.rst#

The index.rst files specify the structure of your documentation.

  • For the index.rst file located in the root folder, add the following content.

.. cheatsheet documentation master file, created by
    sphinx-quickstart on XXX
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.

Course
======


.. toctree::
    :maxdepth: 1
    :caption: Contents:

    courses/index

  • Edit the other index.rst file similarly.

File conf.py#

  • Customize the conf.py file as specified below

# conf.py

...

html_logo = "_static/logo.svg"

...

html_theme = "pydata_sphinx_theme"

...

html_css_files = ['css/custom.css',]

...

html_theme_options = {
    "icon_links": [
            {
                "name": "GitHub",
                "url": "{{my_github_url}}",
                "icon": "fab fa-github-square",
            }
            ]
    }

Build#

  • Tu build your documentation, run the following command :

$ make html

Github Deployment#

In the following, I show how to use github workflow to automatically build and host your documentation.

Project Structure#

  • Create a folder with the following structure

.git/        # add by git init automatically
.github/
    workflows/
        sphinx.yml  # add this
.gitignore  # add this
LICENSE     # add this
README.md   # add this
docs/       # add your sphinx project here

File .git#

  • In the root folder, initialize git tracking using the command

$ git init

This command will create the .git folder automatically.

File .gitignore#

  • Add a .gitignore file in the root folder of your project with the following content

# sphinx build folder
build
docs/build

# tests
tests

# Compiled source #
###################
*.com
*.class
*.dll
*.exe
*.o
*.so
*.c

# Packages #
############
# it's better to unpack these files and commit the raw source
# git has its own built in compression methods
*.7z
*.dmg
*.gz
*.iso
*.jar
*.rar
*.tar
*.zip

# Logs and databases #
######################
*.log
*.sql
*.sqlite

# OS generated files #
######################
.DS_Store?
ehthumbs.db
Icon?
Thumbs.db

File sphinx.yml#

  • In your sphinx.yml file, add the following content. This content allows github to run a new build each time a new push is detected.

name: Sphinx build

on: push

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v2
        - name: Build HTML
        uses: ammaraskar/sphinx-action@0.4
        - name: Upload artifacts
        uses: actions/upload-artifact@v1
        with:
            name: html-docs
            path: docs/build/html/
        - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: docs/build/html

Github Configuration#

  • Create a new repo on github,

  • Push your local project on the main branch of the github repo,

  • In your github repo, configure the settings according to the above screenshot.

Github Configuration