doc(README): add archival notice
This commit is contained in:
parent
d4b136e760
commit
2d1eb82a96
1 changed files with 38 additions and 87 deletions
125
README.md
125
README.md
|
|
@ -1,98 +1,49 @@
|
||||||
<a name="tiara-sphinx-theme"></a>
|
<a name="tiara-sphinx-theme"></a>
|
||||||
# Tiara's Sphinx Theme Reference Implementation
|
# Tiara's Sphinx Theme Reference Implementation
|
||||||
|
|
||||||
> **Heads up**: This is a work-in-progress reference implementation to showcase
|
> 🛌 **NOTICE:** This project is taking a naap. It depends upon
|
||||||
how [Tiara's HTML Theming Reference](https://github.com/ByteB4rb1e/html-theme-ref)
|
[html-theme-ref](https://github.com/byteb4rb1e/html-theme-ref), which hasn't
|
||||||
can integrate with a from-scratch Sphinx documentation theme. I'll be *working
|
stabilized yet. I will restart work around June '25.
|
||||||
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
|
## Installation
|
||||||
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**
|
The program is aimed towards UNIX/GNU in POSIX environments. NT users in
|
||||||
- A **minimalistic yet extensible** Sphinx theme built with a CSS-first mindset.
|
PowerShell may consult `configure.ac` for initial configuration and `Makefile`
|
||||||
- A **reference implementation** to show how HTML themes can integrate
|
for development/build targets.
|
||||||
seamlessly with Sphinx.
|
|
||||||
- A **template** for developers aiming to build documentation themes with
|
|
||||||
clarity and modularity in mind.
|
|
||||||
|
|
||||||
**What This Is NOT**
|
Initialize the project
|
||||||
- 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/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
|
sh ./configure
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Install dependencies (Microsoft PowerShell)**
|
<table>
|
||||||
|
<tr>
|
||||||
```powershell
|
<th></th>
|
||||||
git submodule update --init --remote --recursive && npm install
|
<th></th>
|
||||||
```
|
</tr>
|
||||||
|
<tr>
|
||||||
3. **Preview and experiment**
|
<td>Pipfile.lock</td>
|
||||||
|
<td></td>
|
||||||
TODO
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>requirements.txt</td>
|
||||||
|
<td></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>requirements-dev.txt</td>
|
||||||
|
<td></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>configure</td>
|
||||||
|
<td></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>configure</td>
|
||||||
|
<td></td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>src/sphinx_theme_ref/assets</td>
|
||||||
|
<td></td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue