Wikin v1.3.0 - Parser (wikin.parser) - Documentation

Wikin v1.3.0
PyPI GitHub

No results found for your search.

# Wikin

Documentation generated by Wikin.

## Module: Parser (wikin.parser)

### Classes

ModuleDoc class

Holds documentation data for a single Python module.

WikinParser class

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__ method
`__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 method
`_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 method
`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 method
`_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 method
`_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 method
`_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 method
`_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.