project-name
├── README.rst
├── .gitignore
└── docs
│   └── .gitkeep
└── docsource
    └── .gitkeep

Sphinx documentation sphinx-doc.org: Getting Started sphinx-quickstart command to quickly generate documentation sphinx-quickstart

cd docsource && sphinx-quickstart --no-sep

project-name
├── README.rst
├── .gitignore
├── docs
│   └── .gitkeep
└── docsource
    ├── _build
    │   └── .gitkeep
    ├── _static
    │   └── .gitkeep
    ├── _templates
    │   └── .gitkeep
    ├── .gitkeep
    ├── conf.py
    ├── index.rst
    ├── make.bat
    └── Makefile

one line command

make -C ./docsource html && python3 -m http.server 8000 --bind 127.0.0.1 --directory ./docsource/_build/html

or using the step by step approach

cd ./docsource
make html
cd ./_build/html
python3 -m http.server 8000 --bind 127.0.0.1

Now navigate to localhost:8000.

project-name
├── .gitignore
├── docs/
│   └── .gitkeep
├── docsource/
│   ├── .gitkeep
│   ├── _autosummary/           # sphinx `autosummary` extension generated directory/content
│   ├── _build/
│   │   ├── doctrees/           # sphinx generated directory/content during the `make html` command
│   │   └── html/               # sphinx generated directory/content during the `make html` command
│   ├── _static/
│   │   └── .gitkeep
│   ├── _templates/             # templates needed by `autosummary` and `autodocs`
│   │   ├── .gitkeep
│   │   ├── class.rst
│   │   └── module.rst
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   └── Makefile
├── mytoolbox/                  # example python module/package (by JamesALeedham/Sphinx-Autosummary-Recursion)
│   ├── .DS_Store
│   ├── __init__.py
│   ├── mymodule1.py
│   ├── mymodule2.py
│   └── mysubpackage/
│       ├── __init__.py
│       ├── mymodule3.py
│       └── mysubsubpackage/
│           ├── __init__.py
│           └── mymodule4.py
└── README.rst

From conf.py uncomment the following code to allow sphinx to look in the correct directory where the python packages have been saved:

File: conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('..'))
# the `..` will move up one directory
# make sure you are pointing it to the correct relative/absolute path

Add the built-in sphinx extensions: autodoc and autosummary by replacing: autodoc sphinx-doc.org: autodoc autosummary sphinx-doc.org: autosummary

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

to:

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',  # Core Sphinx library for auto html doc generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables for modules/classes/methods etc
]
# Turn on sphinx.ext.autosummary
autosummary_generate = True

Sphinx autosummary uses Jinja stub page templates files to generate the documentation:

• autosummary/base.rst – fallback template
• autosummary/module.rst – template for modules
• autosummary/class.rst – template for classes
• autosummary/function.rst – template for functions
• autosummary/attribute.rst – template for class attributes
• autosummary/method.rst – template for class methods

. code:

project-name
├── docsource/
│   ├── _templates/             # templates needed by `autosummary` and `autodocs`
│   │   ├── class.rst
│   │   └── module.rst

This has been added to the index.rst page but can be added to any other page.

.. autosummary::
:toctree: _autosummary
:caption: API Reference
:template: module.rst
:recursive:

mytoolbox

%: Makefile
    rm -rf _build               # remove _build folder cache during the local build test process
    rm -rf _autosummary         # remove _autosummary folder cache during the local build test process
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sing python built-in http.server module create a new make file in the root of the project and add the following command:

# using the makefile inside the docs folder
# clean the current build then
# test build docs in local environment and
# start python http.server
live_docs:
    @cp -a ./README.rst ./docsource/README.rst
    make -C ./docsource html && python3 -m http.server 8000 --bind 127.0.0.1 --directory ./docsource/_build/html

This will:

• copy the latest README.rst file (guide) into the docsource directory
• run make html to build the documentation into the _build directory
• the make html command is actually saved in the ./docsource/Makfile
• open a new python http.server to show the static files saved in the previous step

To test the new setup you can run make live_docs from the root of the project.

Add the following to the root Makefile and run make github_docs:

# manual
github_docs:
    rm -rf docs
    mkdir ./docs && touch ./docs/.nojekyll
    @cp -a ./README.rst ./docsource/README.rst
    @make -C ./docsource html
    @cp -a ./docsource/_build/html/. ./docs

# automatic github action push or pull request
github_action_docs:
    rm -rf docs
    mkdir docs && touch docs/.nojekyll
    @cp -a README.rst docsource/README.rst
    rm -rf docsource/_build && mkdir docsource/_build
    rm -rf docsource/_autosummary
    pipx run poetry run sphinx-build -b html docsource docsource/_build/html
    @cp -a docsource/_build/html/* docs

This will:

• remove docs folder cache that might have been previously built to allow for a fresh version
• add a .nojekyll file to github.blog: Bypassing Jekyll on GitHub Pages
• copy the latest README.rst file (guide) into the docsource directory
• run make html to build the documentation into the _build directory
• the make html command is actually saved in the ./docsource/Makefile
• copy the newly built _build static files into docs required by GitHub Pages

name: github pages  🚀

on:
push:
    branches: [main]
pull_request:
    branches: [main]

jobs:
build:
    runs-on: ubuntu-20.04

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.8.5
        uses: actions/setup-python@v2
        with:
        # Semantic version range syntax or exact version of a Python version
        python-version: "3.8.5"
        # Optional - x64 or x86 architecture, defaults to x64
        architecture: "x64"
    # You can test your matrix by printing the current Python version
    - name: Install pipx
        run: python3 -m pip install --user pipx==0.16.0.0
    - name: pipx ensurepath
        run: /home/runner/.local/bin/pipx ensurepath
    - name: pipX PATH
        run: PATH=/home/runner/.local/bin:$PATH
    - name: Install poetry
        run: pipx install poetry==1.1.0
    - name: Test environment
        run: python3 --version ; pip --version ; pipx --version ; pipx run poetry --version ; ls -a ; ls docsource -a
    - name: Install dependencies
        run: pipx run poetry install
    - name: Build website
        run: make github_action_docs
    - name: Commit and Push
        run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
        # use account 'github-actions[bot]' to set the git config
        git add docs
        git commit -m "new github pages"
        git push

This project has been made possible by using/reading:

• github.com: JamesALeedham/Sphinx-Autosummary-Recursion
• docslikecode.com: Yes You Can Use GitHub Pages with Python Sphinx
• github.com: annegentle/create-demo

Project fork from: https://github.com/foolish-dev/ply_sphinx_docs_github_pages/