upgrade to proper-docs (with MaterialX theme) or zensical?

[2bndy5]

At some point we should decide to upgrade to proper-docs (with MaterialX theme) or zensical

Personally I'm waiting to see how fast and how well zensical matures because proper-docs is a community fork of mkdocs (forked out of frustration with the original author of mkdocs).

Originally posted by @2bndy5 in #16 (comment)

[shenxianpeng]

After reading this post https://fpgmaas.com/blog/collapse-of-mkdocs/ what can I say...

Maybe zensical is better than others. I'd like the "wait and see" if the future of MkDocs will continue, seems there's no immediate risk that our docs site

[shenxianpeng]

I took a look at the existing community-maintained options like proper-docs... I feel it may be better to maintain this ourselves.

So I have re-published MkDocs and Material for MkDocs under new package names:

• mkdocs-ng
• mkdocs-ng-material

The commands remain the same. The only requirement is to change the dependencies to the new package names.

Don't promise new features, but will keep the projects alive by fixing bugs, updating dependencies, and handling version upgrades and also review and accept pull requests from others.

[2bndy5]

I feel it may be better to maintain this ourselves.

I had a similar notion. But my idea is more complex: Write my own static site generator (in rust) that supports rST and/or MD as doc inputs. The zensical theme is its own separate repo (MIT licensed), so I thought I'd render the html using those jinja templates. Basically go the same route as zensical, except mimic sphinx instead of mkdocs.

My frustration with sphinx

Some new admin took over sphinx a few years ago, and they have made a lot of breaking changes to its API. So many changes, that they started pinging community leaders for RC testing. These API changes are straining a community of open source devs built around sphinx. I feel like sphinx is quietly abandoning the community that has been supporting it for over a decade.

[shenxianpeng]

I had a similar notion.

We have the same feeling and the willingness to write/maintain good things.

I assume you mentioned someone who's comment always has a letter "A" at the end :)

And just checked Sphinx, it hasn't had any code changes for 4 months.

[2bndy5]

someone who's comment always has a letter "A" at the end :)

Yep. But they (he?) have enablers too (like "yes-men").

... Sphinx, it hasn't had any code changes for 4 months

Yea sphinx v8 and v9 pretty much broke my will to carry the sphinx-immaterial theme forward. When they go silent like that, I usually get to breathe. Now I'm working on a Sphinx replacement written in rust (with a lot of help from AI).

Something else I've been quietly working on with AI

It will be a new git GUI app...