action-sphinx-docs-to-gh-pages

The sphinx documentation in a repository is automatically compiled as 'html' and deployed, by means of the 'gh-pages' branch, with this GitHub Action. 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 ('push' or 'pull request') to be consistent along the action.
Creates a new 'gh-pages' branch 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-pages' branch.

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. Other GitHub Actions can be found at the UIBCDF GitHub site.

Requirements

GitHub Pages taking the source from the branch gh-pages

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.

A Yaml file to create a conda environment with docs compilation dependencies

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").

How to use it

To include this GitHub Action, put 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@v2
        with:
          fetch-depth: 0
      - name: Make conda environment
        uses: conda-incubator/setup-miniconda@v2
        with:
          python-version: 3.7    # 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@v1.0-beta.2
        with:
          branch: main
          dir_docs: docs
          sphinxopts: ''

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.

Input parameters

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'
dir_docs	Path where the sphinx documentation is located	'docs'
sphinxopts	Compilation options for sphinx-build	''

They are placed in the last three lines of the above workflow example file:

      - name: Running the Sphinx to gh-pages Action
        uses: uibcdf/action-sphinx-docs-to-gh-pages@v1.0-beta.2
          with:
            branch: main
            dir_docs: docs
            sphinxopts: ''

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:.

Documentation conda environment

The sphinx documentation will need specific libraries and packages to be compiled. 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.7
  - sphinx
  - sphinx_rtd_theme
  - sphinxcontrib-bibtex
  - nbsphinx
  - recommonmark
  - sphinx-markdown-tables

And 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.yaml

Other tools like this one

This GitHub Action was developed to solve a need of the UIBCDF. And to be used, additionally, as 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.

DevOpsKev/action-sphinx-docs-to-gh-pages