Explore mkdocs alternative

[ecomodeller]

Purpose: Exploring Feasibility

This PR explores the feasibility of simplifying the documentation approach and migrating to Zensical.

Critical Context: MkDocs is Unmaintained

MkDocs has been unmaintained since August 2024:

• No releases in over a year
• Issues and pull requests piling up with no resolution
• Considered a supply chain risk by the Material for MkDocs team
• No maintainer response to community concerns

The Material for MkDocs team created Zensical as the successor:

• Built by the same team that created Material for MkDocs (@squidfunk)
• Designed to overcome MkDocs' architectural limitations and unmaintained status
• Material for MkDocs is entering maintenance mode (February 2026) and will only receive critical bug fixes
• Zensical is the recommended migration path from Material for MkDocs

Source: Material for MkDocs announcement

This isn't a preference - it's about maintaining a secure, supported toolchain.

The Problem with Current Approach

1. MkDocs is Unmaintained (Supply Chain Risk)

• Cannot guarantee continued functionality
• No security updates or bug fixes
• Dependency vulnerabilities won't be patched

2. Material for MkDocs is Sunsetting

• Entering maintenance mode in early 2026
• Team focus shifted to Zensical
• Migration will be necessary eventually

3. mkdocstrings Doesn't Work yet in Zensical

• The ::: directive is broken in Zensical v0.0.16
• Zensical calls mkdocstrings.makeExtension() which doesn't exist
• No fix in 5 releases (v0.0.11 → v0.0.16)
• Build "succeeds" but silently fails to render API docs
  This will be fixed in the near future.

The mkdocstrings plugin enables robust API documentation generation. We are excited to have the author of mkdocstrings, Timothée Mazzucotelli (aka @pawamoy), on our team. Together, we are building a dedicated Zensical module for API documentation.
https://zensical.org/compatibility/plugins/#mkdocstrings

4. Modern IDEs Make API Doc Websites Redundant

• VSCode, PyCharm show NumPy-style docstrings inline with excellent formatting
• Developers get parameter info with autocomplete right where they code
• Navigating to a website is slower than IDE inline docs

The Solution: Migrate to Zensical + Hand-Written Guides

Why Zensical?

Official successor to Material for MkDocs:

• Built by the Material for MkDocs team (@squidfunk)
• Designed to overcome MkDocs' architectural limitations
• Actively developed and supported
• No supply chain risk from unmaintained dependencies

Backward compatible with mkdocs.yml:

• Can use existing configuration format
• Smooth migration path
• No need to rewrite all configuration

Modern architecture:

• 4-5x faster builds through differential build engine
• Better plugin API
• Designed for scalability

Feasibility Assessment

✅ Technical Feasibility: Proven

• Zensical works perfectly with simplified config
• Migration straightforward (~60 line diff)
• Faster builds, all functionality works

✅ Maintenance Feasibility: Improved

• Simpler toolchain (one dependency vs three)
• No plugin compatibility tracking
• No dependency on unmaintained tools

✅ User Experience: Better for Target Audience

• Simpler for inexperienced developers
• IDE-first matches modern workflow
• Less tooling complexity

⚠️ Trade-offs

What we lose:

• Auto-generated function/class listings
• Automatic parameter docs on website
• Systematic coverage of all public APIs

What we gain:

• Actively maintained, secure toolchain
• Simpler, more maintainable setup
• Better alignment with how developers work
• Future-proof architecture