Tutorial
This guide will go over the basics of the project.
Make sure that you’ve already installed it.
Building versioned docs
Initializing project with sphinx and git
If you have problems initializing sphinx and git, then follow these instructions, otherwise you can skip directly to initializing sphinx-versioned-docs
Before we begin make sure you have sphinx install and some git history already in your project. If not, read first steps with sphinx first. If you just want something quick and dirty you can do the following:
$ sphinx-quickstart docs -p projectname -a author -v version --makefile --no-sep -r version -l en -q
$ git checkout -b feature_branch main # Create new branch from main.
$ echo -e "Test\n====\n\nSample Documentation" > docs/index.rst # Create one doc.
$ git add .
$ git commit -m "initial"
$ sphinx-versioned
Initializing sphinx-versioned-docs
Before using the sphinx-versioned-docs to build a versioned documentation. Make sure you have following things done:
[x] Project initialized.
[x] git initialized.
[x] sphinx initilized.
As soon as the above things are complete, you can perform a sanity check run with sphinx. Just go to the documentation folder (typically docs) and run:
$ make html
This should generate a preliminary documentation for your project.
Once you are satisfied with sphinx-build and have succesfully installed the package, you can run the following command to generate the versioned documentation:
$ sphinx-versioned
If you have problems initializing project and running sphinx, then follow at initializing sphinx and git.
Generated output
After the build has succeded, your docs should be available in <output directory>/<branch>/index.html with a version selector menu/badge present.
Note
By default, sphinx-versioned-docs pre-builds the branches to see which of them fails; but this behaviour can be mitigated using the --no-prebuild argument.
Note
Use --no-quite option to get output from the sphinx builder, adjust verbosity using -v
Deploy to github pages via github actions
A sample github action to build and deploy versioned documentation to github-pages is given:
Note
Note the use of fetch-depth: 0 with actions/checkout to ensure all branches are available to build during runtime.
# Simple workflow for deploying static content to GitHub Pages
name: Deploy to github-pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: "3.9"
- name: Run sphinx-versioned to build docs
run: |
python -m pip install -e .[docs]
sphinx-versioned
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
# Upload entire repository
path: 'docs/_build/'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2