[docs] mkdocs material is EOL, move to a zensical docs build

[aireilly]

MkDocs is effectively end-of-life. The underlying MkDocs project has been unmaintained since August 2024. Material for MkDocs is now in maintenance mode — critical bugs and security fixes only for 12 months, no new features. Zensical is the explicit successor from the same creator (squidfunk).

zensical is a drop in replacement in the RTD build, no URL changes etc. Peep the PR RTD build, the search is probably the main difference, zensical uses a new custom client-side search.

This PR:

• Adds Zensical as an alternative docs build to replace the existing MkDocs setup
• zensical.toml == mkdocs.yml with some caveats
• Adds standalone pre-build scripts to replace MkDocs plugins not yet compatible with Zensical (api-autonav, gen-files)
• Both build systems coexist — mkdocs.yml and all MkDocs dependencies remain untouched

Zensical does not support MkDocs plugins. The incompatible plugins are replaced by a build scripts.

# Zensical build
cd docs && make serve    # dev server
cd docs && make build    # static build

# MkDocs build (unchanged)
mkdocs serve             # dev server
mkdocs build             # static build

[github-actions]

👋 Hi! Thank you for contributing to llm-compressor. Please add the ready label when the PR is ready for review.

Note: This is required to complete the testing suite, please only add the label once the PR is code complete and local testing has been performed.

[gemini-code-assist]

Summary of Changes

Hello @aireilly, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request initiates the migration of the project's documentation system from MkDocs to Zensical, a modern successor. The primary goal is to establish Zensical as an alternative build option, allowing for a phased transition given MkDocs' end-of-life status. This involves implementing custom Python scripts to replicate functionalities previously provided by MkDocs plugins, updating build configurations, and ensuring both documentation systems can coexist during the transition period.

Highlights

• Zensical Integration: Introduced Zensical as a parallel documentation build system, intended as a successor to MkDocs, allowing for incremental migration and evaluation.
• MkDocs Plugin Replacement: Replaced incompatible MkDocs plugins (mkdocs-api-autonav, mkdocs-gen-files, mkdocs-awesome-nav, mkdocs-section-index) with custom Python pre-build scripts (gen_api_docs.py, zensical_gen_files.py) to handle API documentation generation and file copying.
• Read the Docs Configuration Update: Updated the .readthedocs.yaml configuration to build documentation using Zensical, while maintaining the existing MkDocs setup for local development.
• New Build Workflow: Modified the docs/Makefile to include new targets (gen, serve, build) for Zensical, streamlining the process of generating content and building the Zensical site.
• Dependency Management: Added zensical and its associated markdown extensions to the project's development dependencies in setup.py, ensuring all necessary tools are available for the new build system.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• .gitignore
  • Added new entries to ignore generated files and directories produced by the Zensical documentation build process.
• .readthedocs.yaml
  • Updated the build configuration to use zensical build for generating HTML documentation, replacing the previous MkDocs build command.
• docs/Makefile
  • Updated the Makefile to support Zensical commands, including a new gen target for pre-build scripts and modified serve and build targets to invoke zensical.
• docs/api/index.md
  • Added YAML frontmatter to the API reference index page, specifying the title for Zensical compatibility.
• docs/scripts/gen_api_docs.py
  • Added a new Python script to programmatically generate API documentation pages and update the Zensical navigation configuration, replacing the mkdocs-api-autonav plugin.
• docs/scripts/zensical_gen_files.py
  • Added a new Python script to copy various documentation files (e.g., examples, developer guides) into the docs directory, serving as a replacement for the mkdocs-gen-files plugin.
• setup.py
  • Modified the dev extra requirements to include zensical and its necessary markdown extensions, while reordering existing MkDocs-related dependencies.
• zensical.toml
  • Added a new Zensical configuration file, defining the site structure, navigation, theme settings, markdown extensions, and plugin configurations for the Zensical documentation build.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request migrates the documentation build system from MkDocs to Zensical, which is a necessary move as MkDocs is reaching its end-of-life. The changes introduce Zensical as a parallel build system, keeping the existing MkDocs setup for now. This is a good incremental approach.

Two new Python scripts, gen_api_docs.py and zensical_gen_files.py, have been added to replace functionality from MkDocs plugins that are not compatible with Zensical. My review focuses on these new scripts.

I've identified a couple of high-severity bugs in the find_project_root function in both scripts that could lead to infinite loops or failure to find configuration files in edge cases. I've also provided a medium-severity suggestion to refactor zensical_gen_files.py to improve its maintainability by reducing code duplication.

Overall, this is a solid PR that handles the migration thoughtfully. Addressing the identified issues will make the new build scripts more robust.

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @aireilly.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[brian-dellabetta]

Thanks for updating this! One question, but otherwise things look good