Architecture of Tiara's Sphinx Theme Reference Implementation

This document outlines the high-level architecture of Tiara's Sphinx Theming Reference, designed to integrate Tiara's HTML Theming Reference with Sphinx. The project adheres to the principles of modularity, accessibility, frugality, and clarity.

Directory Structure Overview

├── .git               # Version control metadata
├── .gitignore         # Ignored files for version control
├── .gitmodules        # Configuration for Git submodules
├── .venv              # Virtualized environment for isolated builds
├── autom4te.cache     # Autotools cache files
├── babel.cfg          # Configuration for Babel (localization)
├── config.log         # Log from Autoconf configuration
├── config.status      # Generated configuration settings
├── configure          # Autoconf-generated build environment script
├── configure.ac       # Autoconf input script for the build process
├── Makefile           # GNU Make build system entry point
├── Pipfile            # Pipenv configuration for development
├── Pipfile.lock       # Lockfile for Pipenv dependencies
├── pyproject.toml     # Metadata for build tools (PEP 518)
├── README.md          # Documentation describing the project
├── requirements.txt   # Generated Python dependencies for runtime (through pipenv)
├── requirements-dev.txt # Generated Python dependencies for development (through pipenv)
├── setup.py           # Python setup script
├── src                # Core implementation of the Sphinx theme
├── tox.ini            # Configuration for Tox (testing)
└── vendor             # External dependencies and HTML theme sources

Core Components

src/

This directory contains the heart of the project: the modular, standards-driven Sphinx theme implementation. It integrates seamlessly with Tiara's HTML Theming Reference, showcasing accessibility-first and CSS-first design principles.

vendor/

Houses external dependencies, including the Git submodule for the HTML theme. The build artifacts from the HTML theme are dynamically compiled via GNU Make and redirected into the src/ directory to ensure streamlined integration.

Key Tools and Workflows

Virtualized build environment

The project utilizes a fully virtualized build environment powered by Python's venv. This ensures consistency across development and runtime environments.

Pipenv and Dependency Management

The project itself is treated as a regular dependency and is added to Pipenv as an editable package, in addtion to development depedencies. Pipenv is then used to generate requirements.txt and requirements-dev.txt.

Pipfile: defines an abstract of all dependencies
pyproject.toml: Defines the dependencies required by the project itself.
requirements.txt: Generated by Pipenv, it includes both the project’s dependencies and the project as an editable package. This ensures seamless initialization of runtime environments.
requirements-dev.txt: Contains additional development dependencies needed for contributors working on the project.

By utilizing Pipenv in this manner, the development environment remains streamlined and virtualized, requiring only Python 3 and the venv module for initialization.

Autotools Integration

GNU Autoconf is leveraged as a unified entry point for initializing the build environment. This setup serves as an orchestrator, extending beyond its traditional use case in compiled languages.

3.5 KiB Raw Blame History Unescape Escape