#selfdoc.strictcli_support

#selfdoc.strictcli_support

First-class support for strictcli-based projects.

Reads .strictcli/schema.json (generated by <app> --dump-schema) for CLI structure (App, commands, flags, args, groups), and produces Markdown documentation pages.

#uses_strictcli

def uses_strictcli(source_paths, base_dir)

Return True if the project has a .strictcli/schema.json file.

The source_paths parameter is accepted for call-site compatibility but is not used -- detection is purely based on the schema file.

#read_schema_json

def read_schema_json(base_dir, source_paths=None)

Read .strictcli/schema.json and translate to the internal format.

Returns a dict with app_name, app_version, app_help, commands (list), and groups (list) -- or None if the schema file does not exist.

The translation preserves new fields from the schema (choices, hidden, deprecated, variadic, passthrough, repeatable, negatable) so downstream consumers can use them.

#_translate_command

def _translate_command(name, cmd)

Translate a schema command dict to the internal format.

#_translate_group

def _translate_group(name, grp)

Translate a schema group dict to the internal format.

#extract_cli_structure

def extract_cli_structure(source_paths, base_dir)

Read the CLI structure from .strictcli/schema.json.

Returns a dict describing the app, its commands, flags, args, and groups -- or raises FileNotFoundError if no schema is found.

The source_paths parameter is accepted for call-site compatibility but is not used.

#expected_cli_page_filenames

def expected_cli_page_filenames(cli_structure)

Return the list of filenames generate_cli_pages would write.

Used by the stale-file cleanup pass to know which CLI page names are "current" so the generated pages from a prior run are not deleted as stale before the new pages have been written.

#_read_existing_cli_description

def _read_existing_cli_description(filepath, default_pattern)

Return the user-customized description from a CLI page.

Returns None if the file does not exist, has no description key, has an empty description, or still has the default auto-generated description matching default_pattern (in which case the caller should recompute it).

Truncated default descriptions (e.g. chelp[:155] cut mid-sentence) are also treated as default-and-overwritable: they are detected by checking whether the existing description is a prefix of the freshly computed default. The caller passes the freshly computed default via default_pattern when it is a plain string, or a compiled regex for the fallback template form. To support both, this helper accepts either a compiled regex (matched against the value) or a plain string (compared as a prefix match against the value).

#generate_cli_pages

def generate_cli_pages(cli_structure, docs_dir)

Generate Markdown documentation pages from cli_structure.

Creates an index page and one page per top-level command group. All pages have generated: true frontmatter and read-only permissions (0o444).

Returns a list of generated filenames (relative to docs_dir).

#_write_page

def _write_page(filepath, content)

Write a generated page atomically with read-only permissions.

#_render_command_page

def _render_command_page(cmd, app_name, nav_order, existing_path=None)

Render a Markdown page for a single command.

If existing_path points to an existing page whose description frontmatter has been hand-edited (i.e. is neither the default chelp[:155] truncation nor the long-form default template), that description is preserved instead of recomputing it.

#_render_group_page

def _render_group_page(grp, app_name, nav_order, existing_path=None)

Render a Markdown page for a command group and its subcommands.

If existing_path points to an existing page whose description frontmatter has been hand-edited (i.e. is neither the default ghelp[:155] truncation nor the long-form default template), that description is preserved instead of recomputing it.

#_fmt_short

def _fmt_short(short)

Format a short flag for table display.