Cansin Acarer

This post assumes you have all your Flask blueprints and other modules in the /app directory. If not, revise these snippets accordingly.

1. Install the Sphinx, with a theme and the autoapi extension:

pip install sphinx sphinx-rtd-theme sphinx-autoapi

2. Create and navigate into the docs directory:

mkdir docs

cd docs

3. Run Sphinx quick start:

sphinx-quickstart

When prompted, type y to create separate directories for source and build.

4. To overwrite the default autoapi template, create this file:

docs\source\_templates\autoapi\index.rst

Type this in it, customize it as you wish. We are doing this to overwrite the default title of API Reference.

Application Reference
=============


This page contains auto-generated API reference documentation [#f1]_.

.. toctree::
   :titlesonly:

   {% for page in pages|selectattr("is_top_level_object") %}
   {{ page.include_path }}
   {% endfor %}

.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

5. Add these to /docs/source/conf.py:

# Add the project root to the Python path
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

# Extensions
extensions = [
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'autoapi.extension'
]

# AutoAPI settings
autoapi_type = 'python'
autoapi_dirs = ['../../app']
autoapi_options = [
    'members',
    'undoc-members',
    'show-inheritance',
    'show-module-summary'
]
autoapi_template_dir = "_templates/autoapi"

# Theme settings
html_theme = 'sphinx_rtd_theme'

6. To make the generated API docs visible in your documentation home page, add a line that says autoapi/index to your index.rst:

.. toctree::
   :maxdepth: 4

   autoapi/index

7. We are ready to generate the HTML files from the docstrings of our application.

.\make.bat html

Continuously Build and Deploy the Docs to Github Pages

Create a Github Actions workflow:

name: Build and Deploy Sphinx Docs

on:
    push:
        branches:
            - main

jobs:
    build-docs:
        runs-on: ubuntu-latest

        steps:
            # Checkout the repository
            - name: Checkout code
              uses: actions/checkout@v3

            # Set up Python
            - name: Set up Python
              uses: actions/setup-python@v4
              with:
                  python-version: "3.9"

            # Install dependencies
            - name: Install dependencies
              run: |
                  python -m pip install --upgrade pip
                  pip install sphinx sphinx-rtd-theme sphinx-autoapi

            # Build the documentation
            - name: Build Sphinx documentation
              run: |
                  cd docs
                  make html

            # Deploy to GitHub Pages
            - name: Deploy to GitHub Pages
              uses: peaceiris/actions-gh-pages@v4
              with:
                  github_token: ${{ secrets.GITHUB_TOKEN }}
                  publish_dir: docs/build/html

After you push this workflow to GitHub, it will create a separate branch named gh-pages. Go to your repository settings and find the Pages menu. Select this branch and hit Save.

This will create another workflow in the Actions of your repository. When that workflow runs successfully, your documentation will be deployed at <your-github-username>.github.io/<your-repo>.

You can see this method in action on my Flask project here:

My Documentation on GitHub Pages

My GitHub Actions