Generate Docs for Python Projects

This document assumes that you have sphinx documentation setup for an existing python project. If not, please refer to document over here → Python Based Development at GQC

Workflow to generate docs

1. Create a new yml file in the .github/workflows folder of the repo with the name docs.yml
2. Push the file to the master branch
3. The workflow will run and create a gh-pages branch for you with the docs on it.

Annotated yml

This section is only for understanding. To create the yml file in the workflows folder, use the final section below.

name: Build Docs   # name of the workflow

on:                # will get triggered on every push to the master branch
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest # use ubuntu-latest operating system to build the docs
    steps:
      - uses: actions/checkout@v3 # checkout the current state of the repository
      - name: Install Dependencies # install the requirements + dev requirements of the package
        run: |
          pip install -e '.[dev]'
      - name: Build Documentation # use the sphinx-build command to generate the docs
        run: |                                  # build the docs in the docs/build folder
          sphinx-build docs/source/ docs/build/
      - name: Deploy to GitHub Pages            # push the docs to the gh-pages branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build/            # directory to use to push the documentation on the branch
          force_orphan: true                    # keeps the branch an orphan

Clean yml (USE THIS ↓)

name: Build Docs

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Dependencies
        run: |
          pip install -e '.[dev]'
      - name: Build Documentation
        run: |
          sphinx-build docs/source/ docs/build/
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/build/
          force_orphan: true