Migrate documentation to Zensical

[jonathan343]

Overview

This PR migrates the existing top-level documentation generation from Material for MkDocs to Zensical.

The developer team at Material for MkDocs announced it was entering into maintenance mode in November 2025 and are now primarily focused on Zensical (see blog post).

Since Zensical already supports the primary features we need, it seems like the best path forward here is for us to migrate.

Note

This PR only migrates the top-level documentation generation. The client-level documentation will need to be fixed upstream at our infrastructure layer.

Preview

Testing

To test these changes locally, checkout these changes and run the following commands:

$ make docs-install
$ make docs
$ make docs-serve
# Open http://127.0.0.1:8000/ in a browser

Important Notes

• The current system uses a hook to dynamically generate the copyright year. Zensical currently doesn't support hooks. For now, we'll just hardcode the current year. Using an inline <script> is bad security practice. There may be other ways, but I don't think it's a big deal to solve right now.
• The current system also relies on literate-nav for defining it's navigation structure. This plugin isn't compatible with Zensical so we need to store the generate the navigation structure and inject it directly into zensical.toml. I'm not the biggest fan of this but didn't find a better solution. It scales linearly so if we have 400 services, the zensical.toml will have 400 lines for navigation.
• docs/javascript/nav-expand.js needed to be updated for Zensical. Basically, the left navigation loses track of where it is when going into a nested operation's page, so this script will activate the relevant parent link.
• I added a requirements-docs.txt which is a lock-file for the dependencies defined in requirements-docs.in. This protects us from transitive dependencies quietly upgrading and breaking out site.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[arandito]

Our release infrastructure uses this file to add the correct dependencies to the nested clients' pyproject.toml. If we release this now before updating our infrastructure to also use zensical, this would remove the necessary dependencies for the docs to be built in the clients.

I'm not sure how many people actually build individual client docs, but maybe we wait to merge this change until we update our release infrastructure?