b65a382fcb
Since the repository is an older attempt at formulating a reference (it was more of a failed boilerplating attempt). I (just) need to rearrange a couple of things before being able to integrate the HTML theme reference.
98 lines
2.8 KiB
Markdown
98 lines
2.8 KiB
Markdown
<a name="tiara-sphinx-theme"></a>
|
||
# 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.
|
||
|
||
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.
|
||
|
||
**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.
|
||
|
||
**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.
|
||
|
||
---
|
||
|
||
## 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
|
||
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
|