Sphinx tips & tricks

Good looking theme: Furo

• example: https://python-gitlab.readthedocs.io/
• huge fonts though, look at https://github.com/pradyunsg/furo/discussions/385

Q: How to serve live preview on Windows without going crazy?

• A: Use WSL and then it’s straightforward

Q: Example of Sphinx->GitLab pages CI?

Q: Example of Sphinx->GitHub Pages CI?

• A: https://github.com/mcejp/propel/blob/master/.github/workflows/pages.yaml
• More recent (2026-01): https://github.com/mcejp/procgenlib/blob/master/.github/workflows/pages.yaml
  • build always, publish only for master

Alternatives

• Sphinx (https://docs.kernel.org/)
• GitHub/GitLab Wiki? Is this usable as static site generator?
• VitePress
• mdBook (https://doc.rust-lang.org/book/, https://docs.hyperdeck.io/)
• mkdocs (https://hsutter.github.io/cppfront/)
• GitBook/HonKit
• Any wysiwyg?
• hugo
• “one of the main reasons why we selected docusaurus is because of the search engine, far better compared with the mkdocs.”

GitLab Pages

docs-build:
  image: ...
  needs: []
  script:
  - ...
  artifacts:
    paths:
    - public

pages:
  image: ...
  needs: [docs-build]
  script:
  - echo Deploying Pages
  artifacts:
    paths:
    - public
  rules:
    # Deploy only on push to master
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

GitLab: Publish docs on tag push, use tag name as version

.gitlab-ci.yml

my_job:
  (...)
  only:
    - tags

config.py

import os

(...)

version = os.getenv("CI_COMMIT_TAG", default=None)
release = version

(...)

# This is the default, but just to be sure:
# html_theme_options = {
#     'display_version': True,
# }

Issue: sphinx-autobuild doesn’t refresh on Python code change

Add --watch=<dir>