Docs

docs

DocsTool — one-shot documentation tree dump.

DocsTool

Bases: AXMTool

Dump README + mkdocs + docs tree in one call.

Registered as ast_docs via axm.tools entry point.

Source code in packages/axm-ast/src/axm_ast/tools/docs.py

class DocsTool(AXMTool):
    """Dump README + mkdocs + docs tree in one call.

    Registered as ``ast_docs`` via axm.tools entry point.
    """

    @property
    def name(self) -> str:
        """Return tool name for registry lookup."""
        return "ast_docs"

    @safe_execute
    def execute(
        self,
        *,
        path: str = ".",
        detail: str = "full",
        pages: list[str] | None = None,
        **kwargs: object,
    ) -> ToolResult:
        """Dump project documentation.

        Args:
            path: Project root directory.
            detail: Detail level — ``toc``, ``summary``, or ``full``.
            pages: Page name substrings to filter (case-insensitive).
            **kwargs: Reserved for future use.

        Returns:
            ToolResult with documentation data.
        """
        project_path = Path(path).resolve()
        if not project_path.is_dir():
            return ToolResult(success=False, error=f"Not a directory: {project_path}")

        from axm_ast.core.docs import discover_docs, format_docs_json

        try:
            result: DocsResult = discover_docs(project_path, detail=detail, pages=pages)
            data = cast("dict[str, object]", format_docs_json(result))
        except Exception as exc:  # noqa: BLE001
            return ToolResult(success=False, error=str(exc))
        try:
            text: str | None = render_docs_text(data, detail)
        except (KeyError, TypeError, AttributeError):
            text = None
        return ToolResult(success=True, data=data, text=text)

name property

Return tool name for registry lookup.

execute(*, path='.', detail='full', pages=None, **kwargs)

Dump project documentation.

Parameters:

Name	Type	Description	Default
path	str	Project root directory.	'.'
detail	str	Detail level — toc, summary, or full.	'full'
pages	list[str] | None	Page name substrings to filter (case-insensitive).	None
**kwargs	object	Reserved for future use.	{}

Returns:

Type	Description
ToolResult	ToolResult with documentation data.

Source code in packages/axm-ast/src/axm_ast/tools/docs.py

@safe_execute
def execute(
    self,
    *,
    path: str = ".",
    detail: str = "full",
    pages: list[str] | None = None,
    **kwargs: object,
) -> ToolResult:
    """Dump project documentation.

    Args:
        path: Project root directory.
        detail: Detail level — ``toc``, ``summary``, or ``full``.
        pages: Page name substrings to filter (case-insensitive).
        **kwargs: Reserved for future use.

    Returns:
        ToolResult with documentation data.
    """
    project_path = Path(path).resolve()
    if not project_path.is_dir():
        return ToolResult(success=False, error=f"Not a directory: {project_path}")

    from axm_ast.core.docs import discover_docs, format_docs_json

    try:
        result: DocsResult = discover_docs(project_path, detail=detail, pages=pages)
        data = cast("dict[str, object]", format_docs_json(result))
    except Exception as exc:  # noqa: BLE001
        return ToolResult(success=False, error=str(exc))
    try:
        text: str | None = render_docs_text(data, detail)
    except (KeyError, TypeError, AttributeError):
        text = None
    return ToolResult(success=True, data=data, text=text)

render_docs_text(data, detail)

Render docs data as compact text for a given detail level.

Parameters:

Name	Type	Description	Default
data	dict[str, object]	Payload from :func:format_docs_json.	required
detail	str	Detail level — toc, summary, or full.	required

Returns:

Type	Description
str	Compact text rendering. Full bodies are reproduced verbatim.

Source code in packages/axm-ast/src/axm_ast/tools/docs_text.py

def render_docs_text(data: dict[str, object], detail: str) -> str:
    """Render docs data as compact text for a given detail level.

    Args:
        data: Payload from :func:`format_docs_json`.
        detail: Detail level — ``toc``, ``summary``, or ``full``.

    Returns:
        Compact text rendering. Full bodies are reproduced verbatim.
    """
    typed = cast("_DocsData", data)
    pages = typed.get("pages") or []
    project = typed.get("project", "project")
    readme = typed.get("readme")
    mkdocs = typed.get("mkdocs")
    extras = (1 if readme else 0) + (1 if mkdocs else 0)
    header = f"ast_docs | {detail} | {project} | {len(pages)} pages +{extras}"

    lines: list[str] = [header]
    _append_file(lines, "\U0001f4d6", readme)
    _append_file(lines, "⚙", mkdocs)
    _append_tree(lines, typed.get("tree"))
    for page in pages:
        _append_page(lines, page, detail)
    return "\n".join(lines)