Re: How to deal with MkDocs?

On 2026-03-17, Michał Górny wrote:
> Hello,
> 
> TL;DR: MkDocs 1.x has been discontinued, 2.x is breaking backwards
> compatibility and infuriating the community, and we have a bunch of
> forks now -- how do we deal with that crap?
> 
> 
> A while ago dev-python/mkdocs was added to Gentoo.  You know, the new
> documentation system that all cool kids use because you then don't have
> to use ReST but instead you do cool Markdown like all the cool GitHub
> kids do.  It got quite popular, and got lots of plugins.  It's now
> handled via docs.eclass.
> 
> Recently upstream discontinued MkDocs 1.x and started working on 2.x. 
> This seems to have caused quite an uproar: apparently upstream not only
> breaks backwards compatibility, but made some questionable changes like
> removing the plugin system entirely [1].
> 
> So mkdocs-material folk has created 'Zensical' as an alternative to
> MkDocs, and then someone forked MkDocs 1.x into 'properdocs'. 
> Unfortunately, this fork is a true fork -- with everything renamed and
> no CLI-wise backwards compatibility (I suspect it's backwards compatible
> with plugins but I have no clue).
> 
> The mkdocs-gen-files plugin now requires *both* mkdocs (1.x) and
> properdocs (as in RDEPEND).
> 
> Where do we go from here?
> 
> If you asked me, I have no interest in maintaining yet another
> documentation system (or two), updating docs.eclass, and waiting a few
> years while projects keep deciding what to switch to (or maybe create a
> third fork, because it's easier to fork than to search for an existing
> fork).  So I would lean towards removing mkdocs support entirely, and
> last riting the whole stack.

I'm for removing mkdocs support, it has never been pleasant to use it in 
ebuilds. By looking at mkdocs.yml you never have the slightest idea what 
plugins are used, and unless the upstream has listed requirements in 
pyproject.toml, good luck finding out that.

And if you manage to figure out dependenices, you often discover that a 
couple of them are not packaged anywhere. At this point you decide that 
packaging them is not worth the hassle.

All that for a small benefit of having local HTML docs when there is no 
software to browse such documentation conveniently except Debian's dwww 
(https://manpages.debian.org/testing/dwww/dwww.7.en.html). And I suspect 
there's a reason it is not packaged anywhere outside of Debian's 
repository family.