aetos/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: regroup homepage into apps/tutorial/services/libraries cards

Browse Source 
- assign each repo a section via config.yml (blog -> apps,
  media-manager -> tutorial, auth-server -> services, rest -> libraries)
- render one card per repo with a bottom-justified action row containing
  one link per available kind (view docs / view wiki / view lib /
  view tutorial)
- switch card grid to three columns with responsive breakpoints and
  taller cards
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-11 23:49:59 +05:30
parent 42e5ed290e
commit bd8ba6e67c
3 changed files with 170 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
_index/index.html
View File

@@ -30,19 +30,25 @@
padding:3px 8px; border-radius:6px; font-size:0.85rem; font-weight:600;
border:1px solid #484f58;
}
.section { width:100%; max-width:900px; margin-bottom:2.5rem; }
.section { width:100%; max-width:1200px; margin-bottom:2.5rem; }
.section h2 {
font-size:1.2rem; color:var(--muted); text-transform:uppercase;
letter-spacing:1.5px; margin-bottom:1rem; border-bottom:1px solid var(--border);
padding-bottom:0.4rem;
}
.grid {
display:grid; grid-template-columns:repeat(auto-fit,minmax(280px,1fr));
gap:1.5rem; width:100%;
display:grid; grid-template-columns:repeat(3, 1fr); gap:1.5rem; width:100%;
}
@media (max-width: 1024px) {
.grid { grid-template-columns:repeat(2, 1fr); }
}
@media (max-width: 640px) {
.grid { grid-template-columns:1fr; }
}
.card {
background:var(--card); border:1px solid var(--border); border-radius:12px;
padding:1.8rem; text-align:left;
padding:1.6rem; text-align:left; display:flex; flex-direction:column;
height:100%; min-height:200px;
transition:transform 0.15s ease,box-shadow 0.15s ease;
}
.card:hover {
@@ -51,11 +57,19 @@
}
.card h3 { color:var(--accent); font-size:1.4rem; margin-bottom:0.4rem; }
.card p { color:var(--muted); font-size:0.95rem; line-height:1.6; }
.card a {
color:var(--accent); text-decoration:none; display:inline-block;
margin-top:0.8rem; font-weight:500;
.card-actions {
margin-top:auto; padding-top:1.2rem; display:flex; flex-wrap:wrap; gap:0.6rem;
}
.card-actions a {
color:var(--accent); text-decoration:none; font-size:0.85rem; font-weight:600;
padding:0.45rem 0.9rem; border:1px solid var(--border); border-radius:999px;
background:rgba(45,212,191,0.06);
transition:border-color 0.15s ease,background 0.15s ease,color 0.15s ease;
}
.card-actions a:hover {
color:var(--accent-dim); border-color:var(--accent);
background:rgba(45,212,191,0.14);
}
.card a:hover { color:var(--accent-dim); text-decoration:underline; }
footer { margin-top:4rem; text-align:center; color:var(--muted); font-size:0.9rem; }
</style>
</head>
@@ -65,86 +79,104 @@
<p class="subtitle">Central documentation hub for Aetoskia projects</p>
</header>
<section class="section">
<h2>Apps</h2>
<div class="grid">
<div class="card">
<h3>Blog API</h3>
<p>A modular, async Blog API backend for FastAPI microservices. Provides streamlined CRUD operations for articles and authors.</p>
<div class="card-actions">
<a href="/blog/" target="_blank">view docs</a>
</div>
</div>
</div>
</section>
<section class="section">
<h2>Tutorial</h2>
<div class="grid">
<div class="card">
<h3>Media Manager Tutorial</h3>
<p>Step-by-step guide to the Media Manager architecture, ingestion pipeline, automation workflows, and integrations.</p>
<div class="card-actions">
<a href="/media-manager/" target="_blank">view tutorial</a>
</div>
</div>
</div>
</section>
<section class="section">
<h2>Services</h2>
<div class="grid">
<div class="card">
<h3>Auth Server</h3>
<p>Aetoskia authentication service. OpenAPI-driven, FastAPI backend for auth flows.</p>
<div class="card-actions">
<a href="/auth-server/api/" target="_blank">view docs</a>
</div>
</div>
</div>
</section>
<section class="section">
<h2>Libraries</h2>
<div class="grid">
<div class="card">
<h3>OpenAPI First</h3>
<p>Design-first API development toolkit enforcing OpenAPI contracts as the single source of truth.</p>
<a href="/openapi-first/lib/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/openapi-first/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>Doc Forge</h3>
<p>Renderer-agnostic Python documentation compiler powering MkDocs and MCP generation across Aetoskia projects.</p>
<a href="/doc-forge/lib/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/doc-forge/wiki/" target="_blank">view wiki</a>
<a href="/doc-forge/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>DAG Pipe</h3>
<p>Deterministic pipeline framework for executing state transformations through a directed acyclic graph (DAG).</p>
<a href="/dagpipe/lib/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/dagpipe/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>Mail Intake</h3>
<p>High-performance email ingestion and processing framework with pluggable adapters and automation workflows.</p>
<a href="/mail-intake/lib/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/mail-intake/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>Omniread</h3>
<p>Unified ingestion and normalization layer for structured and unstructured data sources.</p>
<a href="/omniread/lib/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/omniread/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>Py JWT</h3>
<p>Lightweight, explicit JWT utilities for Python services with strong validation and minimal magic.</p>
<a href="/py-jwt/lib/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/py-jwt/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>Hexa</h3>
<p>Hexagonal architecture framework and toolbox for Python services.</p>
<a href="/hexa/lib/" target="_blank">View Documentation &rarr;</a>
</div>
</div>
</section>
<section class="section">
<h2>APIs</h2>
<div class="grid">
<div class="card">
<h3>Auth Server</h3>
<p>Aetoskia authentication service. OpenAPI-driven, FastAPI backend for auth flows.</p>
<a href="/auth-server/api/" target="_blank">View Documentation &rarr;</a>
</div>
<div class="card">
<h3>Blog API</h3>
<p>A modular, async Blog API backend for FastAPI microservices. Provides streamlined CRUD operations for articles and authors.</p>
<a href="/blog/" target="_blank">View Documentation &rarr;</a>
</div>
</div>
</section>
<section class="section">
<h2>Wiki</h2>
<div class="grid">
<div class="card">
<h3>Doc Forge</h3>
<p>Renderer-agnostic Python documentation compiler powering MkDocs and MCP generation across Aetoskia projects.</p>
<a href="/doc-forge/wiki/" target="_blank">View Documentation &rarr;</a>
<div class="card-actions">
<a href="/hexa/lib/" target="_blank">view lib</a>
</div>
</div>
<div class="card">
<h3>Mongo Ops</h3>
<p>A modular, async MongoDB operations layer for FastAPI microservices. Simplifies CRUD, transactions, and model management.</p>
<a href="/mongo-ops/" target="_blank">View Documentation &rarr;</a>
</div>
</div>
</section>
<section class="section">
<h2>Tutorials</h2>
<div class="grid">
<div class="card">
<h3>Media Manager Tutorial</h3>
<p>Step-by-step guide to the Media Manager architecture, ingestion pipeline, automation workflows, and integrations.</p>
<a href="/media-manager/" target="_blank">View Tutorial &rarr;</a>
<div class="card-actions">
<a href="/mongo-ops/" target="_blank">view wiki</a>
</div>
</div>
</div>
</section>

110
collect.py
View File

@@ -107,19 +107,25 @@ INDEX_TEMPLATE = r"""<!DOCTYPE html>
padding:3px 8px; border-radius:6px; font-size:0.85rem; font-weight:600;
border:1px solid #484f58;
}}
.section {{ width:100%; max-width:900px; margin-bottom:2.5rem; }}
.section {{ width:100%; max-width:1200px; margin-bottom:2.5rem; }}
.section h2 {{
font-size:1.2rem; color:var(--muted); text-transform:uppercase;
letter-spacing:1.5px; margin-bottom:1rem; border-bottom:1px solid var(--border);
padding-bottom:0.4rem;
}}
.grid {{
display:grid; grid-template-columns:repeat(auto-fit,minmax(280px,1fr));
gap:1.5rem; width:100%;
display:grid; grid-template-columns:repeat(3, 1fr); gap:1.5rem; width:100%;
}}
@media (max-width: 1024px) {{
.grid {{ grid-template-columns:repeat(2, 1fr); }}
}}
@media (max-width: 640px) {{
.grid {{ grid-template-columns:1fr; }}
}}
.card {{
background:var(--card); border:1px solid var(--border); border-radius:12px;
padding:1.8rem; text-align:left;
padding:1.6rem; text-align:left; display:flex; flex-direction:column;
height:100%; min-height:200px;
transition:transform 0.15s ease,box-shadow 0.15s ease;
}}
.card:hover {{
@@ -128,11 +134,19 @@ INDEX_TEMPLATE = r"""<!DOCTYPE html>
}}
.card h3 {{ color:var(--accent); font-size:1.4rem; margin-bottom:0.4rem; }}
.card p {{ color:var(--muted); font-size:0.95rem; line-height:1.6; }}
.card a {{
color:var(--accent); text-decoration:none; display:inline-block;
margin-top:0.8rem; font-weight:500;
.card-actions {{
margin-top:auto; padding-top:1.2rem; display:flex; flex-wrap:wrap; gap:0.6rem;
}}
.card-actions a {{
color:var(--accent); text-decoration:none; font-size:0.85rem; font-weight:600;
padding:0.45rem 0.9rem; border:1px solid var(--border); border-radius:999px;
background:rgba(45,212,191,0.06);
transition:border-color 0.15s ease,background 0.15s ease,color 0.15s ease;
}}
.card-actions a:hover {{
color:var(--accent-dim); border-color:var(--accent);
background:rgba(45,212,191,0.14);
}}
.card a:hover {{ color:var(--accent-dim); text-decoration:underline; }}
footer {{ margin-top:4rem; text-align:center; color:var(--muted); font-size:0.9rem; }}
</style>
</head>
@@ -151,16 +165,45 @@ INDEX_TEMPLATE = r"""<!DOCTYPE html>
</html>"""
def _render_section(title: str, cards: list[tuple[str, str, str, str]]) -> str:
SECTION_ORDER = (
("apps", "Apps"),
("tutorial", "Tutorial"),
("services", "Services"),
("libraries", "Libraries"),
)
DEFAULT_SECTION = "libraries"
LINK_KINDS = (("api", "view docs"), ("wiki", "view wiki"), ("lib", "view lib"))
def _card_links(
entry: dict, name: str, base_url: str, kind_urls: dict[tuple[str, str], str]
) -> list[tuple[str, str]]:
"""Build the action links for a repo card from its declared kinds."""
docs = entry.get("docs") or {}
links: list[tuple[str, str]] = []
for kind, label in LINK_KINDS:
if docs.get(kind):
url = kind_urls.get((name, kind), base_url)
links.append((label, url))
if entry.get("kind") == "tutorial":
links.append(("view tutorial", base_url))
return links or [("view docs", base_url)]
def _render_section(title: str, cards: list[tuple[str, str, list[tuple[str, str]]]]) -> str:
if not cards:
return ""
lines = [f'<section class="section">', f"<h2>{title}</h2>", '<div class="grid">']
for t, desc, href, label in cards:
for t, desc, links in cards:
lines.append(f' <div class="card">')
lines.append(f" <h3>{t}</h3>")
lines.append(f" <p>{desc}</p>")
lines.append(f' <a href="{href}" target="_blank">{label} &rarr;</a>')
lines.append(f" </div>")
lines.append(' <div class="card-actions">')
for label, href in links:
lines.append(f' <a href="{href}" target="_blank">{label}</a>')
lines.append(" </div>")
lines.append(" </div>")
lines.append("</div>")
lines.append("</section>")
return "\n".join(lines)
@@ -171,46 +214,35 @@ def build_index_html(
home_urls: dict[str, str],
kind_urls: dict[tuple[str, str], str] | None = None,
) -> str:
lib_cards: list[tuple[str, str, str, str]] = []
api_cards: list[tuple[str, str, str, str]] = []
wiki_cards: list[tuple[str, str, str, str]] = []
tutorial_cards: list[tuple[str, str, str, str]] = []
kind_urls = kind_urls or {}
sections: dict[str, list[tuple[str, str, list[tuple[str, str]]]]] = {}
for entry in config.get("repos", []):
docs = entry.get("docs") or {}
name = entry["name"]
title = _safe_title(entry)
desc = _safe_description(entry)
base_url = home_urls.get(name, f"/{name}/")
if docs.get("lib"):
url = kind_urls.get((name, "lib"), base_url)
lib_cards.append((title, desc, url, "View Documentation"))
if docs.get("wiki"):
url = kind_urls.get((name, "wiki"), base_url)
wiki_cards.append((title, desc, url, "View Documentation"))
if docs.get("api"):
url = kind_urls.get((name, "api"), base_url)
api_cards.append((title, desc, url, "View Documentation"))
section = (entry.get("section") or DEFAULT_SECTION).strip().lower()
sections.setdefault(section, []).append(
(title, desc, _card_links(entry, name, base_url, kind_urls))
)
for entry in config.get("static", []):
kind = entry.get("kind")
name = entry["repo"]
title = _safe_title(entry)
desc = _safe_description(entry)
url = home_urls.get(name, f"/{name}/")
if kind == "api":
api_cards.append((title, desc, url, "View Documentation"))
elif kind == "tutorial":
tutorial_cards.append((title, desc, url, "View Tutorial"))
base_url = home_urls.get(name, f"/{name}/")
section = (entry.get("section") or DEFAULT_SECTION).strip().lower()
sections.setdefault(section, []).append(
(title, desc, _card_links(entry, name, base_url, kind_urls))
)
body = "\n\n".join(filter(None, [
_render_section("Libraries", lib_cards),
_render_section("APIs", api_cards),
_render_section("Wiki", wiki_cards),
_render_section("Tutorials", tutorial_cards),
]))
body = "\n\n".join(
filter(
None,
(_render_section(title, sections.get(key, [])) for key, title in SECTION_ORDER),
)
)
return INDEX_TEMPLATE.format(body=body)

14
config.yml
View File

@@ -12,7 +12,8 @@
# wiki -> /<repo>/ when the wiki is the whole site (e.g. mongo-ops)
# -> /<repo>/wiki/ in combined sites (e.g. doc-forge with lib + wiki)
# mcp -> MCP server on its configured port
# The docs homepage lists a repo once per declared kind (lib, api, wiki).
# The docs homepage shows one card per repo, grouped by its `section`
# (apps, tutorial, services, libraries); card links cover the repo's kinds.
service:
name: aetos-docs
@@ -24,6 +25,7 @@ repos:
source: ../openapi-first
title: OpenAPI First
description: Design-first API development toolkit enforcing OpenAPI contracts as the single source of truth.
section: libraries
docs:
lib: site
mcp: { bundle: docs/mcp, server: openapi_first, port: 8004 }
@@ -32,6 +34,7 @@ repos:
source: ../doc-forge
title: Doc Forge
description: Renderer-agnostic Python documentation compiler powering MkDocs and MCP generation across Aetoskia projects.
section: libraries
docs:
wiki: site
lib: site
@@ -41,6 +44,7 @@ repos:
source: ../dagpipe
title: DAG Pipe
description: Deterministic pipeline framework for executing state transformations through a directed acyclic graph (DAG).
section: libraries
docs:
lib: site
mcp: { bundle: docs/mcp, server: dagpipe, port: 8006 }
@@ -49,6 +53,7 @@ repos:
source: ../mail-intake
title: Mail Intake
description: High-performance email ingestion and processing framework with pluggable adapters and automation workflows.
section: libraries
docs:
lib: site
mcp: { bundle: docs/mcp, server: mail_intake, port: 8002 }
@@ -57,6 +62,7 @@ repos:
source: ../omniread
title: Omniread
description: Unified ingestion and normalization layer for structured and unstructured data sources.
section: libraries
docs:
lib: site
mcp: { bundle: docs/mcp, server: omniread, port: 8003 }
@@ -65,6 +71,7 @@ repos:
source: ../py-jwt
title: Py JWT
description: Lightweight, explicit JWT utilities for Python services with strong validation and minimal magic.
section: libraries
docs:
lib: site
mcp: { bundle: docs/mcp, server: jwtlib, port: 8005 }
@@ -73,6 +80,7 @@ repos:
source: ../hexa
title: Hexa
description: Hexagonal architecture framework and toolbox for Python services.
section: libraries
docs:
lib: site
@@ -80,6 +88,7 @@ repos:
source: ../mongo-ops
title: Mongo Ops
description: A modular, async MongoDB operations layer for FastAPI microservices. Simplifies CRUD, transactions, and model management.
section: libraries
docs:
wiki: site
@@ -87,6 +96,7 @@ repos:
source: ../auth-server
title: Auth Server
description: Aetoskia authentication service. OpenAPI-driven, FastAPI backend for auth flows.
section: services
docs:
api: site
@@ -95,10 +105,12 @@ static:
repo: blog
title: Blog API
description: A modular, async Blog API backend for FastAPI microservices. Provides streamlined CRUD operations for articles and authors.
section: apps
path: blog
- kind: tutorial
repo: media-manager
title: Media Manager Tutorial
description: Step-by-step guide to the Media Manager architecture, ingestion pipeline, automation workflows, and integrations.
section: tutorial
path: media-manager