"""Sphinx extension for automatic Cyclopts CLI documentation."""
from typing import TYPE_CHECKING, Any
import attrs
from cyclopts import __version__
from cyclopts.utils import import_app
if TYPE_CHECKING:
from sphinx.application import Sphinx
from docutils import nodes
from sphinx.application import Sphinx
from sphinx.util import logging
from sphinx.util.docutils import SphinxDirective
logger = logging.getLogger(__name__)
@attrs.define(kw_only=True)
class DirectiveOptions:
"""Configuration for the Cyclopts directive."""
heading_level: int = 2
max_heading_level: int = 6
commands: list[str] | None = None
exclude_commands: list[str] | None = None
# All booleans must have ``False`` default.
no_recursive: bool = False
include_hidden: bool = False
flatten_commands: bool = False
code_block_title: bool = False
skip_preamble: bool = False
@classmethod
def from_dict(cls, options: dict) -> "DirectiveOptions":
"""Create options from directive options dictionary."""
kwargs = {}
for field in attrs.fields(cls):
# Convert underscore to dash for looking up in options
option_name = field.name.replace("_", "-")
if field.type is bool:
# For boolean fields using directives.flag, presence means True
# The value is None when present, absent from dict when not specified
if option_name in options:
kwargs[field.name] = True
# Use default value if not specified
elif option_name in options:
value = options[option_name]
# Handle comma-separated lists for commands and exclude-commands
if field.name in ("commands", "exclude_commands"):
# Parse comma-separated list and strip whitespace
if value:
kwargs[field.name] = [cmd.strip() for cmd in value.split(",") if cmd.strip()]
else:
# Empty string means empty list
kwargs[field.name] = []
else:
kwargs[field.name] = value
# If not specified, the dataclass default will be used
return cls(**kwargs)
@staticmethod
def spec() -> dict[str, Any]:
"""Generate Sphinx option_spec from DirectiveOptions fields."""
from docutils.parsers.rst import directives
type_mapping = {
bool: directives.flag,
int: directives.nonnegative_int,
str: directives.unchanged,
}
option_spec = {}
for field in attrs.fields(DirectiveOptions):
option_name = field.name.replace("_", "-")
# Handle List[str] fields (commands, exclude-commands)
if field.name in ("commands", "exclude_commands"):
validator = directives.unchanged # Will be parsed as comma-separated in from_dict
else:
validator = type_mapping.get(field.type, directives.unchanged)
option_spec[option_name] = validator
return option_spec
def _should_include_command(
command_name: str,
command_path: list[str],
commands_filter: list[str] | None,
exclude_commands: list[str] | None,
) -> bool:
"""Check if a command should be included in documentation.
Parameters
----------
command_name : str
The name of the command.
command_path : list[str]
The full path to the command (including parent commands).
commands_filter : list[str] | None
If specified, only include commands in this list.
exclude_commands : list[str] | None
If specified, exclude commands in this list.
Returns
-------
bool
True if the command should be included.
"""
# Build the full command path for nested commands
full_path = ".".join(command_path + [command_name])
# Check exclusion list first
if exclude_commands:
# Check both the command name and full path
if command_name in exclude_commands or full_path in exclude_commands:
return False
# Check if any parent path is excluded
for i in range(len(command_path)):
parent_path = ".".join(command_path[: i + 1])
if parent_path in exclude_commands:
return False
# Check inclusion list
if commands_filter is not None:
# If a filter is specified, only include if explicitly listed
# Check if command name or full path is in the filter
if command_name in commands_filter or full_path in commands_filter:
return True
# Check if any parent path is included (to include all subcommands)
for i in range(len(command_path)):
parent_path = ".".join(command_path[: i + 1])
if parent_path in commands_filter:
return True
# Also check if just the base command name matches for top-level commands
if not command_path and command_name in commands_filter:
return True
return False
# No filter specified, include by default
return True
def _filter_commands(
commands: dict,
commands_filter: list[str] | None,
exclude_commands: list[str] | None,
parent_path: list[str] | None = None,
) -> dict:
"""Filter commands based on inclusion/exclusion lists.
Parameters
----------
commands : dict
Dictionary mapping command names to App instances.
commands_filter : Optional[List[str]]
If specified, only include commands in this list.
exclude_commands : Optional[List[str]]
If specified, exclude commands in this list.
parent_path : List[str]
Path to the parent command for nested commands.
Returns
-------
dict
Filtered commands dictionary.
"""
if parent_path is None:
parent_path = []
filtered = {}
for name, app in commands.items():
if _should_include_command(name, parent_path, commands_filter, exclude_commands):
filtered[name] = app
return filtered
def _process_rst_content(content: str, skip_title: bool = False) -> list[str]:
"""Process RST content to remove problematic elements."""
lines = content.splitlines()
processed = []
i = 0
while i < len(lines):
line = lines[i]
# Skip title and underline if requested
if skip_title and i == 0 and line.strip() and i + 1 < len(lines):
next_line = lines[i + 1].strip()
if next_line and set(next_line) <= {"-", "=", "^", "~", '"'}:
i += 2
continue
# Skip .. contents:: directive
if line.strip().startswith(".. contents::"):
i += 1
while i < len(lines) and lines[i].strip() and lines[i][0] in " \t":
i += 1
if i < len(lines) and not lines[i].strip():
i += 1
continue
processed.append(line)
i += 1
return processed
def _create_section_nodes(lines: list[str], state: Any) -> list["nodes.Node"]:
"""Create section nodes from RST lines."""
from docutils.statemachine import StringList
result = []
i = 0
while i < len(lines):
line = lines[i]
# Check for section header
if i + 1 < len(lines):
next_line = lines[i + 1].strip()
if next_line and all(c == "-" for c in next_line):
# Create section
section = nodes.section()
title_text = line.strip()
section["ids"] = [title_text.lower().replace(" ", "-").replace("cyclopts-", "cli-cyclopts-")]
section += nodes.title(text=title_text)
# Collect section content
content_lines = []
i += 2 # Skip title and underline
while i < len(lines):
next_line_stripped = lines[i + 1].strip() if i + 1 < len(lines) else ""
if next_line_stripped and all(c == "-" for c in next_line_stripped):
break
content_lines.append(lines[i])
i += 1
if content_lines:
state.nested_parse(StringList(content_lines), 0, section)
result.append(section)
continue
# Check for literal block (::)
if line.strip() == "::":
# Skip the :: line
i += 1
# Skip blank line after ::
if i < len(lines) and not lines[i].strip():
i += 1
# Collect indented content for the literal block
literal_content = []
while i < len(lines) and lines[i].startswith(" "):
# Remove the 4-space indentation
literal_content.append(lines[i][4:])
i += 1
# Create a literal block node directly
if literal_content:
literal_block = nodes.literal_block()
literal_block.rawsource = "\n".join(literal_content)
literal_block.append(nodes.Text("\n".join(literal_content)))
result.append(literal_block)
# Skip any trailing blank line
if i < len(lines) and not lines[i].strip():
i += 1
continue
# Regular content - accumulate consecutive lines
if line.strip():
content_lines = [line]
i += 1
# Collect consecutive non-empty lines that aren't section headers or literal blocks
while i < len(lines):
# Check if this is a section header
next_line = lines[i + 1].strip() if i + 1 < len(lines) else ""
if next_line and all(c == "-" for c in next_line):
break
# Check if this is a literal block
if lines[i].strip() == "::":
break
# Check if this is a blank line
if not lines[i].strip():
# Include the blank line and continue to see if there's more content
content_lines.append(lines[i])
i += 1
# If the next line is also blank or we're at the end, stop
if i >= len(lines) or not lines[i].strip():
break
else:
# Add non-empty line
content_lines.append(lines[i])
i += 1
# Parse all accumulated lines together
para = nodes.paragraph()
state.nested_parse(StringList(content_lines), 0, para)
if para.children:
result.extend(para.children)
else:
i += 1
return result
class CycloptsDirective(SphinxDirective): # type: ignore[misc,valid-type]
"""Sphinx directive for documenting Cyclopts CLI applications."""
has_content = False
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
option_spec = DirectiveOptions.spec()
def run(self) -> list["nodes.Node"]:
"""Generate documentation nodes for the Cyclopts app."""
module_path = self.arguments[0]
opts = DirectiveOptions.from_dict(self.options)
try:
rst_content = self._generate_documentation(module_path, opts)
return self._create_nodes(rst_content, opts)
except Exception as e:
return self._error_node(f"Error generating Cyclopts documentation: {e}")
def _generate_documentation(self, module_path: str, opts: DirectiveOptions) -> str:
"""Generate RST documentation for the app."""
from cyclopts.docs.rst import generate_rst_docs
app = import_app(module_path)
# Call generate_rst_docs directly to access internal no_root_title parameter
return generate_rst_docs(
app,
recursive=not opts.no_recursive,
include_hidden=opts.include_hidden,
heading_level=opts.heading_level,
max_heading_level=opts.max_heading_level,
flatten_commands=opts.flatten_commands,
commands_filter=opts.commands,
exclude_commands=opts.exclude_commands,
no_root_title=True, # Always skip root title in Sphinx context
code_block_title=opts.code_block_title,
skip_preamble=opts.skip_preamble,
)
def _create_nodes(self, rst_content: str, opts: DirectiveOptions) -> list["nodes.Node"]:
"""Create docutils nodes from RST content."""
lines = _process_rst_content(rst_content, skip_title=False) # Title already skipped in generate_docs
# Always use section nodes for better Sphinx integration
return _create_section_nodes(lines, self.state)
def _error_node(self, message: str) -> list["nodes.Node"]:
"""Create an error node with the given message."""
logger.error(message)
return [nodes.error("", nodes.paragraph(text=message))]
def setup(app: "Sphinx") -> dict[str, Any]:
"""Setup function for the Sphinx extension."""
app.add_directive("cyclopts", CycloptsDirective)
return {
"version": __version__,
"parallel_read_safe": True,
"parallel_write_safe": True,
}
