HF-Sphinx-Documentation¶

This project uses Sphinx with the Wagtail theme and customizations to generate HTML documentation.

Project Structure¶

.
├── .github/                         # GitHub configuration
│   └── workflows/                   # GitHub Actions workflows (CI/CD)
│       └── static.yml               # Builds & deploys Sphinx docs to GitHub Pages
│
├── docs/                            # Main Sphinx documentation project
│   ├── README.md                    # Project README (shown on GitHub inside /docs)
│   ├── conf.py                      # Sphinx configuration file
│   ├── index.rst                    # Main documentation entry point (homepage)
│   ├── _static/                     # Custom static files (CSS, images, JS)
│   ├── _templates/                  # Custom HTML templates for Sphinx
│   └── _build/                      # Auto-generated HTML output (should be gitignored)
│
├── .venv/                           # Local Python virtual environment (gitignored)
│
├── requirements.txt                # Python dependencies for building the docs
│
└── .gitignore                       # Files & folders excluded from git tracking

Installation¶

Important

You will need to install Java for plantUML Support.

Clone the repository:

git clone https://github.com/Haiko-Nuding/HF-Sphinx-Documentation.git
cd HF-Sphinx-Documentation

(Optional) Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1 

Install dependencies:

pip install -r requirements.txt

Building the Documentation¶

You can generate the documentation in several ways:

1. Using the Make script (Windows)¶

.\make.bat html

This will generate HTML documentation in the build/html folder.

2. Using Sphinx directly¶

If you have Sphinx installed separately:

sphinx-build -b html docs/ build/html

3. Viewing the documentation¶

After building, open:

build/html/index.html

in your browser to view the documentation.

Running the Spelling Check¶

This project uses sphinxcontrib-spelling to check for typos in the documentation. You can run it in the following ways:

1. Using the Make script (Windows)¶

.\make.bat spelling