utl_sphinx_theme

Introduction

Very simple Sphinx theme loosely derived from sphinx13 which is a nice compact and minimal theme that Sphinx uses for its own documentation.

There are a few small differences, mainly in colors (more brown) and header styling (less chrome). Also adds a couple of theme options (title, logo).

This is mainly used for UTLCo projects and may change in unexpected ways, so if you really want to use this then it may be better to fork it.

Installation

Install the theme:

pip install utl-sphinx-theme

How to use

Add the following line to your Sphinx doc conf.py:

html_theme = 'utl_sphinx_theme'

If you use GitHub workflow actions to build your docs you will also probably need to create a requirements.txt in your docs folder with this package listed in it.

Theme options

Inherits all basic theme options and adds the following:

title

The project title. Used in header as well as the HTML title tag.

logo

The path to the project logo. By default this is _static/logo.svg.

Example configuration entry (conf.py):

html_options = {
    'title': 'MyTitle',
    'logo': '_static/my-logo.svg',
}

Integration with GitHub actions

If there isn’t one already, create a requirements.txt file in your docs directory (where your conf.py is) and add the following dependency line:

https://github.com/utlco/utl-sphinx-theme/archive/refs/heads/main.zip

This will install from the latest source. Alternatively, just add the package name byt itself, which will be installed from PyPI:

utl_sphinx_theme

Example GitHub workflow

name: Docs build

on:
  push:
    branches:    
      - main

    env:
      ACTIONS_RUNNER_DEBUG: true

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - uses: actions/setup-python@v5
      with:
        python-version: '3.10'
    - uses: ammaraskar/sphinx-action@master
      with:
        docs-folder: "docs/"
    - uses: actions/upload-pages-artifact@v3
      with:
        path: docs/_build/html/

  deploy:
    needs: build

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4