Merge pull request #32 from OpenScience-Collective/feature/oscar-docs

Add OSCAR docs tab (rendered from the oscar submodule)

Author: neuromechanist

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "osa"]
 	path = osa
 	url = https://github.com/OpenScience-Collective/osa.git
+[submodule "oscar"]
+	path = oscar
+	url = https://github.com/OpenScience-Collective/oscar.git

mkdocs.yml

@@ -67,6 +67,10 @@ plugins:
   - minify:
       minify_html: true
   - section-index
+  # OSCAR doctrine, rendered from the oscar/ submodule at build time.
+  - gen-files:
+      scripts:
+        - scripts/gen_oscar.py
   # API Reference Generation
   # --------------------------
   # These plugins auto-generate API documentation from OSA source code.
@@ -186,3 +190,17 @@ nav:
           - OSA Platform Overview: osa/presentations/osa-platform.md
       - Development: osa/development.md
       - Version Management: osa/version-management.md
+  - OSCAR:
+      - oscar/index.md
+      - Grounding: oscar/grounding.md
+      - Principles: oscar/principles.md
+      - Archetypes:
+          - Website & docs sites: oscar/archetypes/website.md
+          - Command-line tools: oscar/archetypes/cli.md
+          - Libraries & toolboxes: oscar/archetypes/library.md
+          - Web apps & APIs: oscar/archetypes/web-app-api.md
+          - Data archives: oscar/archetypes/data-archive.md
+          - Research lab sites: oscar/archetypes/lab-website.md
+          - Standards & specs: oscar/archetypes/standard.md
+      - Checklist: oscar/checklist.md
+      - Templates & examples: https://github.com/OpenScience-Collective/oscar

oscar

@@ -0,0 +1,44 @@
+"""Render the OSCAR doctrine into the docs site at build time.
+
+The OSCAR doctrine lives in the OSCAR repo (added here as the ``oscar/``
+submodule), so it has a single source of truth. This mkdocs-gen-files script
+copies the markdown from ``oscar/docs/`` into the virtual site tree under
+``oscar/`` on every build, rewriting repo-relative links (to templates,
+examples, and the like) so they resolve to the OSCAR repo on GitHub.
+
+Nothing is duplicated in git: edit the docs in the OSCAR repo, bump the
+submodule here, and docs.osc.earth reflects the change on the next build.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import mkdocs_gen_files
+
+SRC = Path("oscar/docs")
+REPO = "https://github.com/OpenScience-Collective/oscar"
+
+# Links like ](../../templates/llms.txt) point at files that live in the OSCAR
+# repo, not the docs site. Rewrite any "up and out" link to a GitHub blob URL.
+_UP_AND_OUT = re.compile(r"\]\((?:\.\./)+([^)]+)\)")
+
+
+def rewrite_links(text: str) -> str:
+    return _UP_AND_OUT.sub(lambda m: f"]({REPO}/blob/main/{m.group(1)})", text)
+
+
+if not SRC.is_dir():
+    raise SystemExit(
+        f"OSCAR docs not found at {SRC}. Initialise the submodule with: "
+        "git submodule update --init oscar"
+    )
+
+for src in sorted(SRC.rglob("*.md")):
+    rel = src.relative_to(SRC)
+    dest = rel.with_name("index.md") if rel.name == "README.md" else rel
+    out = (Path("oscar") / dest).as_posix()
+    with mkdocs_gen_files.open(out, "w") as fh:
+        fh.write(rewrite_links(src.read_text(encoding="utf-8")))
+    mkdocs_gen_files.set_edit_path(out, f"{REPO}/edit/main/docs/{rel.as_posix()}")