"""MkDocs plugin for automatic Cyclopts CLI documentation.""" import re from typing import TYPE_CHECKING, Any import yaml from attrs import define, field, validators from cyclopts.docs.markdown import generate_markdown_docs from cyclopts.utils import import_app if TYPE_CHECKING: from mkdocs.config.defaults import MkDocsConfig from mkdocs.structure.files import Files from mkdocs.structure.pages import Page from mkdocs.config import base from mkdocs.config import config_options as c from mkdocs.exceptions import PluginError from mkdocs.plugins import BasePlugin, get_plugin_logger logger = get_plugin_logger(__name__) @define(kw_only=True) class DirectiveOptions: """Configuration for the ::: cyclopts directive.""" module: str = field(validator=validators.instance_of(str)) heading_level: int = field(default=2, validator=validators.instance_of(int)) max_heading_level: int = field(default=6, validator=validators.instance_of(int)) commands: list[str] | None = field(default=None, validator=validators.optional(validators.instance_of(list))) exclude_commands: list[str] | None = field( default=None, validator=validators.optional(validators.instance_of(list)) ) recursive: bool = field(default=True, validator=validators.instance_of(bool)) include_hidden: bool = field(default=False, validator=validators.instance_of(bool)) flatten_commands: bool = field(default=False, validator=validators.instance_of(bool)) generate_toc: bool = field(default=True, validator=validators.instance_of(bool)) code_block_title: bool = field(default=False, validator=validators.instance_of(bool)) skip_preamble: bool = field(default=False, validator=validators.instance_of(bool)) @classmethod def from_directive_block( cls, directive_text: str, *, default_heading_level: int | None = None, default_max_heading_level: int | None = None, ) -> "DirectiveOptions": """Parse options from a ::: cyclopts directive block. Expected format: ::: cyclopts module: myapp.cli:app heading_level: 2 max_heading_level: 6 recursive: true commands: - cmd1 - cmd2 Parameters ---------- directive_text : str The directive text to parse. default_heading_level : int | None Default heading level from plugin config. Used if :heading-level: not specified. default_max_heading_level : int | None Default max heading level from plugin config. Used if :max-heading-level: not specified. """ lines = directive_text.strip().split("\n") # Remove the ::: cyclopts line if lines and lines[0].strip().startswith("::: cyclopts"): lines = lines[1:] yaml_content = "\n".join(lines) options = yaml.safe_load(yaml_content) or {} if not isinstance(options, dict): raise TypeError("Invalid YAML in ::: cyclopts directive: expected a dictionary") if "module" not in options: raise ValueError('The "module" option is required for ::: cyclopts directive') if default_heading_level is not None: options.setdefault("heading_level", default_heading_level) if default_max_heading_level is not None: options.setdefault("max_heading_level", default_max_heading_level) # Convert keys with dashes to underscores normalized_options = {key.replace("-", "_"): value for key, value in options.items()} try: return cls(**normalized_options) except TypeError as e: raise ValueError(f"Error creating DirectiveOptions: {e}") from e # Regex to match ::: cyclopts directive blocks # The pattern matches: # - "^::: cyclopts\n" - the directive start on its own line # - "(?:[ \t]+.*\n?)*" - zero or more indented YAML lines (with optional trailing newline for EOF) DIRECTIVE_PATTERN = re.compile( r"^::: cyclopts\n(?:[ \t]+.*\n?)*", re.MULTILINE, ) def process_cyclopts_directives(markdown: str, plugin_config: Any) -> str: """Process all ::: cyclopts directives in markdown content. Parameters ---------- markdown : str The markdown content containing ::: cyclopts directives. plugin_config : CycloptsPluginConfig The plugin configuration with default values. If None, uses DirectiveOptions defaults. Returns ------- str The markdown content with directives replaced by generated documentation. """ # Find all code blocks to exclude from processing code_blocks = [] # Find fenced code blocks (triple backticks or tildes) fenced_pattern = re.compile(r"^[`~]{3,}.*?^[`~]{3,}", re.MULTILINE | re.DOTALL) for match in fenced_pattern.finditer(markdown): code_blocks.append((match.start(), match.end())) # Find indented code blocks (lines starting with 4 spaces or tab) # Indented code blocks are preceded by a blank line and consist of lines starting with 4 spaces/tab lines = markdown.split("\n") in_indented_block = False block_start = 0 current_pos = 0 for i, line in enumerate(lines): line_len = len(line) + 1 # +1 for the newline # Check if this line starts an indented code block if not in_indented_block: # Previous line must be blank (or be the first line) prev_blank = i == 0 or not lines[i - 1].strip() # Current line must start with 4 spaces or a tab and have content is_indented = (line.startswith(" ") or line.startswith("\t")) and line.strip() if prev_blank and is_indented: in_indented_block = True block_start = current_pos else: # Check if we're still in the indented block is_indented = (line.startswith(" ") or line.startswith("\t")) and line.strip() is_blank = not line.strip() # End block if we hit a non-indented, non-blank line if not is_indented and not is_blank: code_blocks.append((block_start, current_pos)) in_indented_block = False current_pos += line_len # If we ended while still in an indented block, add it if in_indented_block: code_blocks.append((block_start, current_pos)) def is_in_code_block(pos: int) -> bool: """Check if a position is inside a code block.""" for start, end in code_blocks: if start <= pos < end: return True return False def replace_directive(match: re.Match) -> str: # Skip if this match is inside a code block if is_in_code_block(match.start()): return match.group(0) directive_text = match.group(0) try: default_heading = plugin_config.default_heading_level if plugin_config else None default_max_heading = plugin_config.default_max_heading_level if plugin_config else None options = DirectiveOptions.from_directive_block( directive_text, default_heading_level=default_heading, default_max_heading_level=default_max_heading, ) app = import_app(options.module) markdown_docs = generate_markdown_docs( app, recursive=options.recursive, include_hidden=options.include_hidden, heading_level=options.heading_level, max_heading_level=options.max_heading_level, generate_toc=options.generate_toc, flatten_commands=options.flatten_commands, commands_filter=options.commands, exclude_commands=options.exclude_commands, no_root_title=True, # Skip root title in plugin context code_block_title=options.code_block_title, skip_preamble=options.skip_preamble, ) return markdown_docs except Exception as e: raise PluginError(f"Error processing ::: cyclopts directive: {e}") from e # Replace all directives in the markdown processed = DIRECTIVE_PATTERN.sub(replace_directive, markdown) return processed class CycloptsPluginConfig(base.Config): # type: ignore[misc] """Configuration schema for the Cyclopts MkDocs plugin.""" default_heading_level = c.Type(int, default=2) # type: ignore[attr-defined] default_max_heading_level = c.Type(int, default=6) # type: ignore[attr-defined] class CycloptsPlugin(BasePlugin[CycloptsPluginConfig]): # type: ignore[misc] """MkDocs plugin to generate Cyclopts CLI documentation. Usage in mkdocs.yml: plugins: - cyclopts: default_heading_level: 2 Usage in Markdown files: ::: cyclopts :module: myapp.cli:app :heading-level: 2 :recursive: true :commands: init, build :exclude-commands: debug """ def on_page_markdown(self, markdown: str, *, page: "Page", config: "MkDocsConfig", files: "Files", **kwargs) -> str: """Process ::: cyclopts directives in markdown content. This event is called after the page's markdown is loaded from file but before it's converted to HTML. """ if "::: cyclopts" not in markdown: return markdown return process_cyclopts_directives(markdown, self.config)