doc(ARCHITECTURE): init

ARCHITECTURE.md

@@ -0,0 +1,80 @@
+# 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.