Implementation:Axolotl ai cloud Axolotl Generate Examples Docs

Knowledge Sources	Axolotl
Domains	Documentation, Code_Generation
Last Updated	2026-02-07 00:00 GMT

Overview

Python script that auto-generates Quarto model guide documentation from an allowlist of example directories, rewriting internal links and copying assets.

Description

The generate_examples_docs.py script reads an allowlist (examples-allowlist.yml) that specifies which example directories to publish as documentation. For each allowed example, it reads the README.md, strips the first H1 heading (replaced by Quarto frontmatter), rewrites internal markdown links to point to the correct .qmd output files, copies local image assets to the docs output directory, and generates properly formatted Quarto pages. It also auto-generates an index page listing all model guides. Key functions include read_allowlist for loading the YAML allowlist, rewrite_readme_links for converting inter-README links to inter-QMD links with correct relative paths, rewrite_and_copy_assets for handling local images, and update_quarto_yml for automatically updating the _quarto.yml sidebar with the generated model guide entries. The script supports nested sub-entries (e.g., magistral/think, magistral/vision) and creates proper hierarchical navigation.

Usage

This script runs as a Quarto pre-render hook (configured in _quarto.yml). It can also be run standalone. Use it whenever example README files are added, modified, or the allowlist changes.

Code Reference

Source Location

• Repository: Axolotl
• File: docs/scripts/generate_examples_docs.py
• Lines: 1-424

Signature

def slugify(name: str) -> str: ...
def read_allowlist() -> list: ...
def find_readme(folder: Path) -> Path | None: ...
def remove_first_h1(md: str) -> tuple[str, str | None]: ...
def rewrite_and_copy_assets(md: str, src_dir: Path, dest_assets_root: Path) -> str: ...
def rewrite_readme_links(md, src_dir, examples_dir, parent_index_only, current_src_path, allowlist_entries, current_output_path) -> str: ...
def write_qmd(out_path: Path, title: str, body_md: str): ...
def update_quarto_yml(generated: list[tuple[str, str, str]]): ...
def main(): ...

Import

# Run as script:
# python docs/scripts/generate_examples_docs.py

I/O Contract

Inputs

Name	Type	Required	Description
examples-allowlist.yml	YAML file	Yes	List of example directory names to generate docs for
examples/*/README.md	Markdown files	Yes	Source README files for each example
_quarto.yml	YAML file	Yes	Quarto config to update with generated sidebar entries

Outputs

Name	Type	Description
docs/models/*.qmd	Quarto files	Generated model guide pages
docs/models/index.qmd	Quarto file	Index page listing all model guides
docs/models/assets/	Directory	Copied image assets from example READMEs
_quarto.yml (updated)	YAML file	Updated sidebar with model guide entries

Usage Examples

Run Standalone

# Generate example documentation
python docs/scripts/generate_examples_docs.py

Allowlist Format

# docs/scripts/examples-allowlist.yml
examples:
  - name: magistral
    title: Magistral
  - name: magistral/think
    title: Magistral Think
  - name: llama-3
  - qwen3

Related Pages

• Environment:Axolotl_ai_cloud_Axolotl_Python_Runtime