Skip to content

IATI/sphinx-theme

Repository files navigation

IATI Sphinx Theme

How do I use IATI Sphinx Theme?

Please see the IATI Sphinx Theme Documentation for usage instructions.

How do I contribute to IATI Sphinx Theme?

Install dependencies

pip install -r requirements_dev.txt

Update dependencies

python -m piptools compile --extra=dev -o requirements_dev.txt pyproject.toml
pip install -r requirements_dev.txt

Run linting

black iati_sphinx_theme/
isort iati_sphinx_theme/
flake8 iati_sphinx_theme/
mypy iati_sphinx_theme/

Documentation with live preview

  1. In one terminal, build the CSS in watch mode

    npm run build:watch
    
  2. In a separate terminal, install the Sphinx theme then start the docs development server:

    pip install -e .
    sphinx-autobuild -a docs docs/_build/html --watch iati_sphinx_theme/
    

Testing a local version of the theme against another project

To run a local version of the theme with another project, e.g. my-docs, take the following steps:

  1. Clone the sphinx-theme repository, and checkout the branch or tag you want to use.

  2. Run the following command in the sphinx-theme directory, to build the CSS for the theme.

    npm run build
    
  3. Go to my-docs directory, and install the Sphinx theme

    pip install -e /path/to/sphinx-theme
    
  4. Set the html_theme option in your conf.py

    html_theme = "iati_sphinx_theme"
  5. Start the docs development server:

    pip install sphinx-autobuild
    sphinx-autobuild docs docs/_build/html