How to deploy Sphinx documentation site on your server

Sphinx is a tool for creating technical documentation.

It supports both reStructuredText and MyST Markdown.

In this tutorial I will show how to start a documentation site, enable Markdown support, install the Book theme (my personal favorite) and deploy it as a static site with Appliku.

Table of Contents

Requirements
Repository:
Create a sphinx project
Commit and push to Github
Deploy Sphinx Documentation site
- Create and add a server for Sphinx Documentation Site
- Create a static site from GitHub repository

Requirements¶

For this tutorial you need:

You need to have Python 3.11 or higher installed on your computer.
git
GitHub account
Appliku Account

Repository:¶

Source code is available on GitHub appliku/sphinxtutorial

Create a sphinx project¶

Create environment and install dependencies

mkdir sphinxtutorial
cd sphinxtutorial
python3 -m venv env
source env/bin/activate
pip install sphinx myst-parser sphinx-book-theme
pip freeze > requirements.txt

Start a project:

sphinx-quickstart --sep -a "Author Name" -p "Sphinx Tutorial" -l en -r "" .

Create .gitignore file

env/
.idea/
__pycache__/
*.py[cod]
*$py.class
.vscode/
.DS_Store
.AppleDouble
.LSOverride
build/

in source/conf.py edit extensions and theme:

extensions = ['myst_parser']
html_theme = 'sphinx_book_theme'

Since we plan to use Markdown, let's remove source/index.rst file and create source/index.md

# Sphinx Tutorial

Welcome to our amazing Sphinx Tutorial

```{toctree}
:maxdepth: 2
:caption: Contents


```

Now you can go back to terminal and type make html (python environment should be activated already).

This will generate our html code in build/html directory.

Open the file in the browser: build/html/index.html

Sphinx Initial Tutorial

Let's see how navigation for other pages will work.

In the source directory create a file about.md

# Hello, I am author of this site

Save it. Now in the index.md file add this page to toctree

# Sphinx Tutorial

Welcome to our amazing Sphinx Tutorial

```{toctree}
:maxdepth: 2
:caption: Contents

about
```

And now run make html again.

Back to the browser, refresh the page.

Sphinx documentation Markdown main page toctree

You can see the link to the about page. Click on it.

Another page in Sphinx documentation

Commit and push to Github¶

In the terminal type:

git init
git add .
git commit -m"Initial commit"

Now go to GitHub.com/new and create a new repository.

Create GitHub repository for Sphinx Documentation site

Since repository is empty, GitHub offers some commands to push the code. We need the git remote add origin, select and copy the line, paste in the terminal and run it.