80 lines
3.5 KiB
Markdown
80 lines
3.5 KiB
Markdown
# 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.
|