Migrate from mkdocs

[lorentzenchr]

See https://github.com/orgs/ProperDocs/discussions/33.

Maybe there are other alternatives.

Maybe also switch mkdocs-material to zensical, squidfunk/mkdocs-material#8523

Related

• https://fpgmaas.com/blog/collapse-of-mkdocs/
• https://github.com/orgs/ProperDocs/discussions/33
• ⚠️ We're now in maintenance mode squidfunk/mkdocs-material#8523

[dangotbanned]

I'd say (https://github.com/zensical/zensical/) seems the most compelling choice (long-term).

Last time I checked though it seemed like the mkdocstrings-equivalent was still a WIP - not sure if that's still the case?

Pinging @MarcoGorelli as this is new and very sudden drama

[lorentzenchr]

For the meantime - short term solution - I went with properdocs in my own package just now. It works and is a very easy transition, see lorentzenchr/model-diagnostics#216.

[dangotbanned]

In the immediate-term, we should probably pin our docs dependencies (mkdocs/mkdocs#4077 (comment))

narwhals/pyproject.toml

Lines 90 to 100 in bb698e1

	docs = [
	"black", # required by mkdocstrings_handlers
	"jinja2",
	"duckdb",
	"narwhals[sql]",
	"markdown-exec[ansi]",
	"mkdocs",
	"mkdocs-autorefs",
	"mkdocs-material",
	"mkdocstrings[python]",
	"mkdocstrings-python>=1.16",

[FBruzzesi]

I think the only blocker to move to zensical for now would be the unavailability of hooks, that we currently use to generate this.md and backend-completeness pages.

See zensical unsupported settings and zensical compatibility/features/extensions.

---

I agree with pinning mkdocs versions for the time being

[MarcoGorelli]

thanks for the discussion - maybe let's start by pinning and then just see what happens for a bit?

[FBruzzesi]

I started a branch (docs/migrate-to-zensical) to see what it would take to migrate and what features are missing.

I think that I was able to migrate completely, the only difference is that hooks need to be manually run in CI (and locally) to build the api-completeness and this.md pages.

[dangotbanned]

I'm quite excited by zensical.toml 😂