diff --git a/README.md b/README.md index 3649b6d..c76c37b 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,49 @@ # 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/ByteB4rb1e/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. +> 🛌 **NOTICE:** This project is taking a naap. It depends upon + [html-theme-ref](https://github.com/byteb4rb1e/html-theme-ref), which hasn't + stabilized yet. I will restart work around June '25. -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. +## Installation -**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. +The program is aimed towards UNIX/GNU in POSIX environments. NT users in +PowerShell may consult `configure.ac` for initial configuration and `Makefile` +for development/build targets. -**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. +Initialize the project ---- - -## 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/ByteB4rb1e/html-theme-ref). - ---- - -## Getting Started - -1. **Clone the Repo** - -```sh -git clone https://bitbucket.org/tiaracodes/sphinx-theme-ref.git ``` - -2. **Install dependencies (POSIX-ish shells)** - -```sh sh ./configure ``` -2. **Install dependencies (Microsoft PowerShell)** - -```powershell -git submodule update --init --remote --recursive && npm install -``` - -3. **Preview and experiment** - -TODO +
| + | + |
|---|---|
| Pipfile.lock | ++ |
| requirements.txt | ++ |
| requirements-dev.txt | ++ |
| configure | ++ |
| configure | ++ |
| src/sphinx_theme_ref/assets | ++ |