Skip to content

docs(site): unified microrobotica.org with sphinx-multiproject + PyData theme - #2

Merged
NicholasEhsanRoy merged 1 commit into
mainfrom
docs/multiproject-site
May 7, 2026
Merged

docs(site): unified microrobotica.org with sphinx-multiproject + PyData theme#2
NicholasEhsanRoy merged 1 commit into
mainfrom
docs/multiproject-site

Conversation

@NicholasEhsanRoy

Copy link
Copy Markdown
Contributor

Summary

Unified docs site for the three projects (MADDENING, MIME, MICROROBOTICA) deployed to GitHub Pages → `microrobotica.org`.

  • Sphinx multiproject layout: one shared `conf.py`, three projects switched via `$PROJECT` env var. Subprojects pulled in as git submodules (`docs/projects/{maddening,mime}`) tracking each repo's `main`.
  • PyData Sphinx Theme, `sphinx-design` cards, MyST.
  • Landing page hero auto-plays both showcase videos (dipole-arm closed-loop control + MIME's de Jongh replication) immediately on entry, then a 3-card project grid.
  • Videos served via `html_extra_path` from `docs/assets/videos/`, so they live with the docs source rather than sphinx's `_static/`.
  • Doxygen → breathe re-wired for the MICROROBOTICA project; `make all` runs Doxygen then builds all three subprojects.
  • New `.github/workflows/docs.yml` builds on PR, deploys to GH Pages on push to `main`. Submodule-aware checkout.
  • `CNAME` points the deployed site at `microrobotica.org`.

Domain / TLS rollout (manual, post-merge)

  1. Merge this PR — first deploy will land at `.github.io/MICROROBOTICA/`.
  2. In the repo's Settings → Pages:
    • Set source to "GitHub Actions"
    • Set custom domain to `microrobotica.org`
    • Tick "Enforce HTTPS" once the cert is issued
  3. At your DNS provider for `microrobotica.org`, add A records pointing the apex to GitHub Pages (185.199.108.153 / .109.153 / .110.153 / .111.153) and an AAAA for IPv6 (2606:50c0:8000::153 / :8001::153 / :8002::153 / :8003::153). Optionally a CNAME from `www.microrobotica.org` → `.github.io`.

Test plan

  • `make all` builds locally with no errors (warnings only — see follow-ups below)
  • `_build/html/index.html` references `videos/*.mp4` and the videos exist in the build output
  • `_build/html/maddening/index.html` and `_build/html/mime/index.html` build from their submodule sources
  • `docs.yml` workflow run on PR is green
  • After merge: GH Pages shows the live site at the org domain, then at `microrobotica.org`

Known follow-ups

  • A few warnings remain from pre-existing broken xrefs inside MADDENING (`developer_guide/documentation_standards.md` references a top-level `CONTRIBUTING`), and from empty doc subdirs in MIME — both tracked in MIME PR docs(site): scaffolding notice, per-project repo links, video fullscreen #4.
  • Submodule pin for MIME advances once that PR merges; just run `git submodule update --remote --merge` from `docs/`.

🤖 Generated with Claude Code

…ta theme

The new docs site lives in MICROROBOTICA/docs/ and bundles three
projects (MADDENING, MIME, MICROROBOTICA) into a single deployable
GitHub Pages target backed by the microrobotica.org domain.

Layout
------
* `docs/conf.py` — shared configuration; sphinx-multiproject switches
  the active project via `$PROJECT` (microrobotica | maddening | mime).
* `docs/projects/{maddening,mime}` — git submodules tracking each
  project's `main`. Their `docs/` subdirs are the subproject sources.
* `docs/index.rst` — landing page. Hero block autoplays the two
  showcase videos (dipole-arm closed-loop control, MIME's de Jongh
  replication) immediately on page load, then a 3-card grid links to
  the three projects.
* `docs/_static/custom.css` — hero + card styling layered on PyData.
* `docs/assets/videos/*.mp4` — copied to `<output>/videos/` via
  `html_extra_path` so the hero `<video>` tags resolve.
* `docs/Makefile` — `make all` runs maddening, mime, microrobotica in
  sequence into `_build/html/{,maddening/,mime/}` and writes
  `.nojekyll` + the CNAME.
* `docs/CNAME` — `microrobotica.org`.
* `docs/requirements.txt` — sphinx, multiproject, pydata-sphinx-theme,
  myst-parser, sphinx-design, breathe, linkify.

CI
--
* `.github/workflows/docs.yml` builds on every PR and deploys
  `docs/_build/html/` to GitHub Pages on push to `main`. Submodules
  are checked out recursively; doxygen/graphviz installed before the
  breathe build.

Doxygen / breathe
-----------------
* The microrobotica project loads breathe and points it at
  `_doxygen/xml`. The Makefile re-runs Doxygen before the sphinx
  build so the C++ XML is fresh.

Misc
----
* Light prose polish on `docs/user_guide/index.md` and
  `docs/developer_guide/index.md` — replaced the "Content pending"
  stub and rewrote the broken `../../CONTRIBUTING.md` link as an
  absolute github.com URL.
* `.gitignore`: stop ignoring `_static/` and `_templates/` — they
  now hold versioned theme assets, not generated output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@NicholasEhsanRoy
NicholasEhsanRoy merged commit 217ea09 into main May 7, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant