Skip to content
Sphinx: Render docs

documentation: Use Sphinx for building HTML documentation #2

Sign in to view logs

documentation: Use Sphinx for building HTML documentation

documentation: Use Sphinx for building HTML documentation #2

Workflow file for this run

.github/workflows/sphinx.yml at 80bdbe6
name: "Sphinx: Render docs"
on:
pull_request: {}
push:
branches:
- main
tags:
- 'v*.*.*'
workflow_dispatch: {}
jobs:
build:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
permissions:
contents: write
steps:
#----------------------------------------------
# check-out repo and set-up python
#----------------------------------------------
- name: Check out repository
uses: actions/checkout@v4
- name: Set up python
id: setup-python
uses: actions/[email protected]
with:
python-version: '3.11'
#----------------------------------------------
# Install and configure Poetry, or restore from cache
#----------------------------------------------
- name: Load cached Poetry installation
id: cached-poetry
uses: actions/[email protected]
with:
path: ~/.local # the path depends on the OS
key: poetry-docs-0 # increment to reset cache
- name: Install Poetry
if: steps.cached-poetry.outputs.cache-hit != 'true'
uses: snok/install-poetry@v1
with:
virtualenvs-create: true
virtualenvs-in-project: true
installer-parallel: true
#----------------------------------------------
# load cached venv if cache exists
#----------------------------------------------
- name: Load cached venv
id: cached-poetry-dependencies
uses: actions/[email protected]
with:
path: .venv
key: boardwalk-docs-venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
#----------------------------------------------
# install your root project, if required
#----------------------------------------------
- name: Install project, with dependencies foor building documentation
run: poetry install --no-interaction --with=docs --sync
- name: Run 'make docs', to build documentation
run: poetry run make docs
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: html-docs
# Lower default retention -- the artifacts can be rebuilt from source, if needed
retention-days: 14
# Don't include the doctrees subdir; it's just pickled data Sphinx generates to make the HTML
path: |
docs/build/
!docs/build/doctrees
- name: Deploy documentation to the gh-pages branch for publishing
uses: peaceiris/actions-gh-pages@v4
if: github.ref == 'refs/heads/main'
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/build/html