diff --git a/README.md b/README.md index 441f0db..c314ed7 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,98 @@ -# 🚀 Welcome to your new awesome project! + +# Tiara's Sphinx Theme Reference Implementation +> **Heads up**: This is a work-in-progress reference implementation to showcase + how [Tiara's HTML Theming Reference](https://github.com/oxbqkwwxfrqccwtg/html-theme-ref) + can integrate with a from-scratch Sphinx documentation theme. I'll be *working + backwards*, so expect the project to align with this *README*, not the other + way around. -## Development +This implementation is designed to elevate Sphinx documentation through a +modular, standards-driven approach. Built from the ground up using Tiara's HTML +Theming Reference, this project reflects a commitment to accessibility, +frugality, and adherence to the UNIX philosophy. -### Hot-Reloading +**What This Is** +- A **minimalistic yet extensible** Sphinx theme built with a CSS-first mindset. +- A **reference implementation** to show how HTML themes can integrate + seamlessly with Sphinx. +- A **template** for developers aiming to build documentation themes with + clarity and modularity in mind. -For a more seamless development workflow, it is possible to host the demo -through a built-in web server with hot-reloading enabled. When accessing the -site through a JavaScript-enabled browser, it will automatically reload once -changes made to the source (`src/tiararodneycom_theme`) are detected. +**What This Is NOT** +- A pre-packaged Sphinx theme ready for production use. +- A general-purpose theming framework—this is specific to the philosophy behind + Tiara's HTML Theming Reference. -To run the server, execute the following command: +--- + +## Why Use This? + +For developers seeking a straightforward and modular solution, this reference +implementation provides a clear and adaptable foundation. It’s designed to +empower users to create documentation themes that reflect their specific +requirements without unnecessary complexity. + +### Key Principles: + +1. **Accessibility First** + +Fully compliant with a11y standards to make documentation inclusive + +2. **Frugal Engineering** + +Lightweight, efficient design for optimal performance. + +3. **CSS First** + +Declarative styling ensures better maintainability. + +4. **UNIX Philosophy** + +Each piece does one thing well—and nothing more. + +5. **Customizability** + +Easily adapt the theme to suit your documentation needs. + +--- + +## Goals + +This project demonstrates how Tiara's HTML Theming Reference integrates with +documentation platforms like Sphinx by: + +- **Showcasing Modularity**: Focusing on separation of concerns for clean, + maintainable code. +- **Exploring Scalability**: Demonstrating how to standardize HTML theming + across platforms. +- **Promoting Standards**: Adhering to W3C, accessibility guidelines, and UNIX + principles. + +For the philosophy behind this, see [Tiara's HTML Theming Reference README](https://github.com/oxbqkwwxfrqccwtg/html-theme-ref). + +--- + +## Getting Started + +1. **Clone the Repo** ```sh -$ python3 -m pipenv run autobuild-demo +git clone https://bitbucket.org/tiaracodes/sphinx-theme-ref.git ``` -Additionally, when working with static content (`src/tiararodneycom_static`), -you may launch a *webpack-dev-server* in parallel for hot-reloading static -files. The *sphinx-autobuilder* will pick up any changes made by -*webpack-dev-middleware* so you can keep on accessing the server hosted through -the `autobuild-demo` command. - -To start the `webpack-dev-server`, execute: +2. **Install dependencies (POSIX-ish shells)** ```sh -$ npm run autobuild +sh ./configure ``` + +2. **Install dependencies (Microsoft PowerShell)** + +```powershell +git submodule update --init --remote && npm install +``` + +3. **Preview and experiment** + +TODO