This article will cover the full process to document your code with Sphinx to GitHub pages via GitHub-actions in 2 main sections :
- How to Create Sphinx Documentation in Python
- How to automatically create and deploy to GitHub pages via GitHub actions
Clone the repo used in this article : https://github.com/RGGH/jubilant-lamp
View the Sphinx generated documentation from this project here on GitHub pages: https://rggh.github.io/jubilant-lamp/
What is Sphinx?
“Sphinx is a documentation generator written and used by the Python community. It is written in Python, and also used in other environments.” ~ wikipedia
What are GitHub Actions?
You can configure a GitHub Actions workflow to publish your Sphinx documentation when changes are pushed to a specific branch to publish your site. GitHub actions are available once you have created a workflow.
Read more here on how to create a workflow
# This is a basic workflow to help you get started with Actions name: Build-sphinx-docs # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ master ] pull_request: branches: [ master ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 - name: Set up Python 3.10 uses: actions/setup-python@v2 with: python-version: "3.10" # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - name: Build HTML run: | cd docs/ make html - name: Run ghp-import run: | ghp-import -n -p -f docs/_build/html # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project.
Credit : https://github.com/niketagrawal for the yaml file
The yaml file
Inside this file you can see that the GitHub action starts an ubuntu vm and uses “ghp-import” which imports your generated html into GitHub pages.
Deploying to GitHub pages using ghp import
The workflow will create the files shown below and then shortly after, import them into GitHub pages.
- name: Build HTML run: | cd docs/ make html - name: Run ghp-import run: | ghp-import -n -p -f docs/_build/html
To understand how to use Sphinx to GitHub Pages via GitHub Actions let’s understand the Sphinx part a bit more.
I’ve covered this previously in this article here, so check that out before reading the rest of this page.
There was one ‘gotcha’ that I spent ages trying to sort however…
The Python code for the project that I was using for this trial were called “mw.py” and “hw.py”
I kept getting this error though:
WARNING: autodoc: failed to import module 'hw'; the following exception was raised:
No module named 'hw'
WARNING: autodoc: failed to import module 'mw'; the following exception was raised:
No module named 'mw'
This was showing up when I ran `make html`
Once I adjusted the conf.py file to have abspath to include the directory of the python code it worked.
import os import sys sys.path.insert(0, os.path.abspath('../jl'))
*You’ll find most examples show a conf file with the abs path of
sys.path.insert(0, os.path.abspath('..')) however, so pay attention to this if you get errors.
Adding additional Python files
So you have Sphinx installed, GitHub repo set up, the workflow is working and the GitHub pages are updating when you modify your existing code. But how do you add additional Python files?
1: Create a new python file with some code in the same directory as the existing Python files
2: cd to the top directory and run
sphinx-apidoc -o docs src/ where src/ is your source code directory. In my case I ran
sphinx-apidoc -o docs jl/
3: Add the name of the Python file to modules.rst – but without the “.py” file extension however!
4: Commit and push to GitHub. *Note: You do NOT have to run “make html” again because the workflow runs Sphinx for you.
5: Wait a few mins and then check your GitHub pages and you will see the updated documentation. In my case a 3rd link appeared for the “lw” module.
Sphinx to GitHub Pages via GitHub Actions : Conclusion
This took me a few hours to get working, based on minimal prior experience, nevertheless what I built is a repo where the Documentation is dynamically create from the commit.
If you add more Python files to your project you will need to rerun
sphinx-apidoc -o docs src/ where src/ is the directory containing your Python files.
*Rather than “src” it would be better to use your project name.
Tip: make sure “__init__.py” files exist in each directory where Python files are located.
I’d suggest experimenting with Sphinx and get it to generate documentation locally first before progressing to the GitHub workflow to generate it rather than jump in at the deep end!
Note: Even though GitHub actions create the html files you will still need Sphinx installed locally to help create the “rst” files and upload them, so run Sphinx to set this up on the computer you code on, and once you commit to the remote ‘master’ at GitHub the GitHub action will have the files it needs to recreate the same documentation and deploy it. Note if you use ‘main’ then edit the yaml file to match.
~/Documents/python/rd/jl master ⇣1 tree -L 2 1 ✘ . ├── docs │ ├── _build │ ├── conf.py │ ├── hw.rst │ ├── index.rst │ ├── make.bat │ ├── Makefile │ ├── modules.rst │ ├── mw.rst │ ├── _static │ └── _templates ├── jl │ ├── hw.py │ ├── __init_.py │ ├── mw.py │ └── __pycache__ ├── Makefile ├── README.md ├── requirements.txt └── setup.sh
Thanks for reading, I wish you success with what can be a particularly confusing concept if you are new to it.
If you want a recommendation for web hosting, check out : https://webdock.io/