Wikin
Documentation generated by Wikin.
Module: Parser (wikin.parser)
Classes
Holds documentation data for a single Python module.
A parser that scans Python files for docstrings and specially formatted variable comments.
This parser utilizes the built-in ast module to traverse Python files and extract classes,
functions, methods, along with their docstrings and signatures.
Attributes
| Name | Type | Description |
|---|---|---|
| root_dir | str | The root directory to scan for Python files. |
| modules | list | A list of parsed module documentation objects. |
| ignore_spec | PathSpec | A PathSpec object used to filter out ignored files based on .wikinignore. |
__init__(self, root_dir: str)
Initialize the parser with a root directory or a single file path.
Args
| Name | Type | Description |
|---|---|---|
| root_dir | str | The target root directory path or file path from which to extract docs. |
_load_ignore_spec(self)
Loads ignore patterns from docs/.wikinignore if it exists.
Returns
| Type | Description |
|---|---|
| Optional[pathspec.PathSpec] | A configured PathSpec if the ignore file is found, otherwise None. |
parse(self)
Perform a recursive search for Python files and extract documentation from them.
This method walks through the root directory, identifies all valid Python files (excluding those in junk directories or matched by the ignore spec), and parses them to populate the internal modules list.
Returns
| Type | Description |
|---|---|
| List[ModuleDoc] | A list containing all uniquely documented modules found. |
_parse_file(self, file_path: str, module_name: str)
Parses a single Python file using the ast module.
Extracts the module-level docstring, classes, functions, and specially annotated variables, formatting them with properties and typing information.
Args
| Name | Type | Description |
|---|---|---|
| file_path | str | Path to the .py file. |
| module_name | str | Dot-separated module name used for the documentation title. |
Returns
| Type | Description |
|---|---|
| ModuleDoc | Module object containing extracted and grouped documentation structures. |
_extract_metadata(self, docstring: str, original_name: str)
Extracts Wikin-specific metadata from the module docstring.
Allows modules to formally override their display name by including a special YAML-like snippet in their root docstring block.
Args
| Name | Type | Description |
|---|---|---|
| docstring | str | The raw module docstring block. |
| original_name | str | The default dot-separated underlying module name. |
Returns
| Type | Description |
|---|---|
| tuple | A tuple mapping (display_name, cleaned_docstring). |
_process_docstring(self, text: Optional[str])
Parses Google and Numpy style docstrings and converts their sections into Markdown tables.
This function sequentially detects specific section headers such as Args:, Returns:, and Raises:
to dynamically generate strict markdown tables inside the description string.
Args
| Name | Type | Description |
|---|---|---|
| text | Optional[str] | The original unformatted docstring representation. |
Returns
| Type | Description |
|---|---|
| str | Flow-processed docstring containing fully constructed Markdown table elements. |
_parse_function(self, node: ast.AST, source: str)
Internal helper to create a FunctionDoc from an AST node.
Constructs the full function formatting structure, building definitions containing type hints,
decorators (@property, @classmethod), async structures, and argument names.
Args
| Name | Type | Description |
|---|---|---|
| node | ast.AST | The AST representation block dictating the function or method footprint. |
| source | str | Processed full text representation of the file code, used specifically for matching exact inline python 3.8 constraints. |
Returns
| Type | Description |
|---|---|
| FunctionDoc | Documented container including function's name wrapper, generated signature path, and attached processed docstring block. |