#selfdoc.gen

#selfdoc.gen

Auto-generate documentation pages from project structure.

#GenResult

Result of a generate_docs call, tracking written and deleted files.

#_should_skip_dir

def _should_skip_dir(dirname)

Return True if a directory name should be pruned during source walks.

#_has_generated_marker

def _has_generated_marker(filepath)

Check whether a Markdown file has generated: true in its frontmatter.

Returns True if the file starts with --- frontmatter containing generated: true, False otherwise (including when the file does not exist or cannot be read).

#_file_to_module_path

def _file_to_module_path(file_path, base_dir, language)

Convert a source file path to a module/package path string.

The path is computed relative to base_dir (the project root) so that the resulting module path matches what :-: ref path="..." expects.

For Python: mylib/config.py -> mylib.config For Go: pkg/handler.go -> pkg/handler For TypeScript/JavaScript: src/utils.ts -> src/utils

#_module_to_filename

def _module_to_filename(module_path, language)

Convert a module path to a Markdown filename for docs/.

Replaces dots (Python) or slashes (Go/TS/JS) with dashes. E.g. selfdoc.config -> selfdoc-config.md E.g. pkg/handler -> pkg-handler.md

#_read_go_module_name

def _read_go_module_name(base_dir)

Read the module name from go.mod in base_dir.

Returns the last path segment of the module path (e.g. "myapp" from "github.com/user/myapp"), or None if go.mod is missing or unparseable.

#_go_root_package_name

def _go_root_package_name(base_dir)

Determine the filename stem for the root Go package.

Reads the module name from go.mod; falls back to the project directory basename.

#_extract_go_package_description

def _extract_go_package_description(pkg_dir)

Extract the package doc comment from a Go package directory.

Reads .go files (excluding _test.go), preferring doc.go, then the file matching the directory name, then any file with a package doc comment. Returns the first line of the doc comment (truncated to 155 chars), or None.

#_collect_go_packages

def _collect_go_packages(source_paths, base_dir, exclude_patterns)

Walk source paths and group .go files by parent directory (package).

Returns a list of (module_path, pkg_dir_abs) tuples sorted by module_path. Excludes test files and files matching exclude_patterns. The module_path is source-path-qualified: for a root package under router/, the module_path is "router" (not "."). For a sub-package middleware/ under router/, it is "router/middleware". This ensures uniqueness across multiple source paths.

#_is_excluded

def _is_excluded(rel_path, exclude_patterns)

Check whether a relative path matches any exclusion glob pattern.

Supports **/ prefix as "match at any depth" by stripping the prefix and testing against every path component and the basename. Plain patterns are matched against the full path, the basename, and each directory component.

#_read_existing_description

def _read_existing_description(filepath)

Return the user-customized description from a page's frontmatter.

Returns None if the file does not exist, has no description key, or still has the default auto-generated description (in which case the caller should recompute it from the current module name).

#_generate_page_content

def _generate_page_content(module_name, module_path, nav_order, existing_description=None, docstring_description=None, language=None)

Build the Markdown content for a generated documentation page.

If existing_description is provided, it is used verbatim as the page's description frontmatter value. Otherwise, if docstring_description is provided (extracted from the module's docstring), it is used. Finally, if neither is available, the default auto-generated template is used.

language is emitted as a lang attribute on the ref directive to disambiguate in multi-language projects.

#_generate_index_content

def _generate_index_content(generated_pages)

Build the gen-index.md page listing all generated pages with links.

generated_pages is a list of (module_name, md_filename) tuples, already sorted by module name.

#_remove_stale_generated

def _remove_stale_generated(docs_dir, new_filenames)

Delete previously generated files that are no longer in the new set.

Only removes files whose frontmatter contains generated: true.

Returns a list of deleted filenames (basenames, not full paths).

#_get_locale_docs_dirs

def _get_locale_docs_dirs(config, base_dir)

Return a list of (locale_code, docs_dir) for generation.

For single-locale projects without locale subdirectories, returns [("", docs_dir)] so generation goes to docs/ directly. For multi-locale projects, returns [(code, docs/code/), ...] for each configured locale.

#generate_docs

def generate_docs(config, base_dir='.')

Auto-discover project source files and generate documentation pages.

For multi-language projects, groups source entries by language and runs a generation pass for each language group. Stale cleanup runs once after all groups so one language's output is never deleted by another's pass.

For multi-locale projects, generates pages under docs/{locale_code}/ for each configured locale. For single-locale projects without locale subdirectories, generates directly under docs/.

Returns a GenResult with written and deleted file paths relative to the docs directory.

#_generate_docs_for_dir

def _generate_docs_for_dir(config, base_dir, language, extractor, docs_dir, source_paths)

Generate docs for a single language group in one directory.

source_paths is the list of source path strings for this language group (already extracted from config by the caller).

Stale cleanup and index generation are NOT done here -- the caller (generate_docs) handles them after all language groups have generated.

Returns a tuple of (GenResult, index_pages) where index_pages is a list of (module_name, md_filename) for the combined index page.

#_make_root_file_header

def _make_root_file_header(template_path)

Build the header comment for a generated root file.

#generate_root_files

def generate_root_files(config, base_dir='.')

Resolve root-file templates and write them to the project root.

Reads config["root_files"] (a list of template paths like "docs/_CLAUDE/"). Each template is resolved via the project's directive resolver, then written with an auto-generated header and read-only (0o444) permissions.

Returns a list of output paths relative to base_dir.