# 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.