The Sphinx documentation in a repository is automatically compiled as 'html'
and deployed, by means of the gh-pages branch, with this GitHub Actions to
GitHub Pages. The user has only to be sure that the repository accomplishes a couple of
requirements.
In summary, this GitHub action does the following:
- Takes the author and SHA id of the trigger action (
pushorpull request) to be consistent along the action. - Creates a new
gh-pagesbranch if this is not already in the repository. - Compiles the sphinx documentation in the directory and branch specified by the user.
- Pushes the output html documentation to the
gh-pagesbranch.
This GitHub Action was developed by the Computational Biology and Drug Design Research Unit -UIBCDF- at the Mexico City Children's Hospital Federico Gómez (see also Contributers). Other GitHub Actions can be found at the UIBCDF GitHub site.
There is no need to have a gh-pages branch already in the repository. This action will create it for you. But once
this GitHub action runned for first time, make sure that GitHub Pages is taking the web source code from the branch
gh-pages. In the github repository go to 'Settings -> Pages -> Source' and check that no other branch is selected as
source.
The compilation of your sphinx documentation requires dependencies that can be solved with a temporary conda environment. Make sure that the repository has a Yaml file with the details to make this environment (see the section "Documentation conda environment").
To include this GitHub Action, create a YAML file (named sphinx_docs_to_gh_pages.yaml, for instance)
with the following content in the directory .github/workflows of your repository:
name: Sphinx docs to gh-pages
on:
push:
branches:
- main
# workflow_dispatch: # Un comment line if you also want to trigger action manually
jobs:
sphinx_docs_to_gh-pages:
runs-on: ubuntu-latest
name: Sphinx docs to gh-pages
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Make conda environment
uses: conda-incubator/setup-miniconda@v2
with:
python-version: 3.10 # Python version to build the html sphinx documentation
environment-file: devtools/conda-envs/docs_env.yaml # Path to the documentation conda environment
auto-update-conda: false
auto-activate-base: false
show-channel-urls: true
- name: Installing the library
shell: bash -l {0}
run: |
python setup.py install
- name: Running the Sphinx to gh-pages Action
uses: uibcdf/action-sphinx-docs-to-gh-pages@v2.1.0
with:
branch: main
dir_docs: docs
sphinx-apidoc-opts: '--separate -o . ../'
sphinx-apidoc-exclude: '../*setup* ../*.ipynb'
sphinx-opts: ''Two things need to be known to run the GitHub Actions without further work: the meaning of the input parameters and the YAML file to make a temporary Conda environment where the sphinx documentation can be compiled.
These are the input parameters of the action:
| Input parameters | Description | Default value |
|---|---|---|
branch |
Name of the branch where the sphinx documentation is located | main |
branch-checkout-args |
Arguments to pass to git checkout: git checkout ${checkout-args} "${branch}" |
'' |
dir_docs |
Path where the sphinx documentation is located | docs |
sphinx-apidoc |
With sphinx-apidoc | true |
sphinx-apidoc-exclude |
With sphinx-apidoc | *setup* tests* |
sphinx-apidoc-opts |
Options for sphinx-apidoc (default outputs to dir_docs and searches for modules one level up) | '-o . ../' |
sphinx-opts |
Compilation options for sphinx-build | '' |
They are placed in the last lines of the above workflow example file:
- name: Running the Sphinx to gh-pages Action
uses: uibcdf/action-sphinx-docs-to-gh-pages@v2.1.0
with:
branch: main
dir_docs: docs
sphinx-opts: ''
sphinx-apidoc-opts: '--separate -o . ../'
sphinx-apidoc-exclude: '../*.ipynb'In case your sphinx documentation is placed in a directory named 'docs' in the 'main' branch to be
compiled with no further options, you can do without the section with:.
The Sphinx documentation will need specific libraries and packages to be compiled. There are a few options to achieving
this, one is to create a Conda environment in which to build the
documentation. Alternatively if your package includes the [options.extras_require] docs section you can install these.
They can be specified in a Conda environment file. This way, a temporary enviroment can be made and activated to compile the documentation with all dependencies satisfied. Write a file in the repository with the following content:
name: docs
channels:
- conda-forge
- defaults
dependencies:
# Write here all dependencies to compile the sphinx documentation.
# This list is just an example
- python=3.10
- sphinx
- sphinx_rtd_theme
- sphinxcontrib-bibtex
- nbsphinx
- recommonmark
- sphinx-markdown-tablesAnd replace the value of the workflow input parameter environment-file: with the right path to your documentation conda enviroment file. In
the case of the above example ('devtools/conda-envs/docs_env.yaml'):
jobs:
sphinx_docs_to_gh-pages:
steps:
- name: Make conda environment
uses: conda-incubator/setup-miniconda@v2
with:
# Replace with the path to your documentation conda enviroment file
environment-file: devtools/conda-envs/docs_env.yamlMany Python packages use setuptools for configuring installation via the setup.cfg file. One section of this is
the [options.extras_require] where packages not required for running the package but used in testing or building
documentation can be listed. To list your documentation build requirements add the following to your setup.cfg
[options.extras_require]
docs =
sphinx<5.0
myst_parser
pydata_sphinx_theme
sphinx_markdown_tables
sphinx_rtd_theme
sphinxcontrib-mermaidThen in your sphinx_docx_to_gh_pages.yaml that you have created under the .github/workflows/ directory replace the
step with -name Make conda environment (see above example) with the following steps which will setup the specified
Python version and then install the docs requirements listed in your setup.cfg.
jobs:
sphinx_docs_to_gh-pages:
steps:
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: 3.10
- name: Installing the Documentation requirements
run: |
pip3 install .[docs]This GitHub Action was developed to solve a need of the UIBCDF. And to be used, additionally, as an example of house-made GitHub Action for researchers and students in this lab.
Other tools you can find in the market doing these same tasks are mentioned below. We recognize and thank the work of their developers. Many of those GitHub Actions were used by us to learn how to set up our own one.
If you think that your GitHub Action should be mentioned here, fell free to PR with a new line.