From 4faf82085b53e2efdff4cd96b93c8c6d0983432b Mon Sep 17 00:00:00 2001 From: Alessandro Griseta Date: Thu, 30 Apr 2026 17:15:44 +0100 Subject: [PATCH] Explain how to build documentation locally --- CONTRIBUTING.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9d058a56..82249b3c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,6 +119,19 @@ The project uses a documentation system that combines static headers with dynami 3. **Generated docs** are created in `pkg/yqlib/doc/*.md` by concatenating headers with test-generated content 4. **Documentation is synced** to the gitbook branch for the website +### Previewing documentation locally + +```bash +uv venv +source .venv/bin/activate +uv pip install mkdocs-material +deactivate +source .venv/bin/activate +cp -r pkg/yqlib/doc/ mkdocs +mkdocs build +mkdocs serve +``` + ### Updating Operator Documentation #### For Test-Generated Documentation @@ -151,6 +164,7 @@ For documentation not in the master branch: ### Documentation Best Practices + - **Write clear, concise examples** in test scenarios - **Use meaningful variable names** in examples - **Include edge cases** and error conditions @@ -226,4 +240,4 @@ Note: PRs with small changes (e.g. minor typos) may not be merged (see https://j - **Check existing issues**: Search GitHub issues for similar problems - **Create an issue**: If you can't find a solution, create a detailed issue - **Ask questions**: Use GitHub Discussions for general questions -- **Join the community**: Check the project's community channels \ No newline at end of file +- **Join the community**: Check the project's community channels