Skip to content

Module inari.collectors

collectors - Store module members, and build markdown documents from docstrings.

Classes

BaseCollector

class BaseCollector(self, abs_path: str = "", name_to_path: Optional[dict[str, str]] = None)

Base class for collecting objects with docstrings.

Attributes

  • name_to_path (dict[str, str]): Mapping of {"module.name.class": "module/name#class"} .
  • doc (str): Docstrings of the object.
  • abs_path (str): Absolute path of the object.

Args

  • abs_path (str): Absolute path of the object.
  • name_to_path (dict[str, str]): Mapping of name and path.

Methods

doc_str

def doc_str(self) -> str

Create documents from its contents.

Returns

  • str: Created from docstrings and annotations.

ClassCollector

class ClassCollector(self, cls: type, abs_path: str, name_to_path: dict[str, str])

Class with methods and properties. Attribute docs should be written in class docstring like this:

Attributes

  • cls (type): Target class.
  • variables (list[VariableCollector]): Class properties.
  • methods (list[FunctionCollector]): Methods of the class.
  • hash_ (str): Used for HTML id.

Args

Base classes

Methods

doc_str

def doc_str(self) -> str

Create documents from its contents.

Returns

  • str: Created from docstrings and annotations.

init_methods

def init_methods(self) -> None

init_variables

def init_variables(self) -> None

FunctionCollector

class FunctionCollector(self, f: Callable[..., Any], name_to_path: dict[str, str], abs_path: str)

Functions and methods.

Attributes

  • function (Callable[..., Any]): Target function.
  • hash_ (str): Used for HTML id.

Args

Base classes

Methods

doc_str

def doc_str(self) -> str

Create documents from its contents.

Returns

  • str: Created from docstrings and annotations.

ModuleCollector

class ModuleCollector(
    self,
    mod: ModuleType,
    out_dir: Union[str, os.PathLike[str]],
    name_to_path: Optional[dict[str, str]] = None,
    out_name: Optional[str] = None,
    enable_yaml_header: bool = False,)

Module docs, submodules, classes, functions, and variables.

Attributes

  • mod (ModuleType): Module to make documents.
  • submodules (dict[str, ModuleCollector]): key-value pair of paths and submodules, wrapped by ModuleCollector .
  • variables (list[VariableCollector]): list of module-level variables, wrapped by VariableCollector .
  • classes (list[ClassCollector]): list of public classes, wrapped by ClassCollector .
  • functions (list[FunctionCollector]): list of public functions, wrapped by FunctionCollector .
  • out_dir (pathlib.Path): Output directly.
  • filename (str): Output filename, like index.md , submodule.md .
  • relpaths (dict[str, tuple[str, str]]): Store relational paths. See inari.collectors.ModuleCollector.make_relpaths .
  • enable_yaml_header (bool): a flag for deciding whether to include yaml header.

Args

  • mod (ModuleType): Module to make documents.
  • out_dir (Union[str, Path]): Output directory.
  • name_to_path (dict): See BaseCollector .
  • out_name (str): Output file name.
  • enable_yaml_header (bool): a flag for deciding whether to include yaml header.

Base classes

Methods

doc_str

def doc_str(self) -> str

Create documents from its contents.

Returns

  • str: Created from docstrings and annotations.

init_classes

def init_classes(self) -> None

Find public classes defined in the module.

init_functions

def init_functions(self) -> None

Find public functions in the module.

init_submodules

def init_submodules(self) -> None

Find submodules.

init_vars

def init_vars(self) -> None

Find variables having docstrings.

make_links

def make_links(self, doc: str) -> str

Create internal link on back-quoted name.

To ignore this, append a space like "foo.bar " .

make_relpaths

def make_relpaths(self) -> None

Create mapping between object name to relative path.

`ful.path.to.mod.cls` -> [`cls`](../../mod.md#cls)

make_yaml_header

def make_yaml_header(self) -> str

Make yaml header from given values.

remove_old_submodules

def remove_old_submodules(self) -> None

Remove documents and collectors of deleted modules.

write

def write(self) -> None

Write documents to files. Directories are created automatically.

VariableCollector

class VariableCollector(
    self,
    var: object,
    name_to_path: dict[str, str],
    abs_path: str,
    name: Optional[str] = None,
    doc: Optional[str] = None,)

Module variables and class properties.

Attributes

  • var: Module-level object or class property, not module/class/function.
  • name (str): Name of the object.

Args

  • var (object): Target object.
  • name_to_path (dict[str, str]): See BaseCollector .
  • abs_path (str): See BaseCollector .
  • name (str): Fallback of var.__name__ .
  • doc (str): Fallback of inspect.getdoc(var) .

Base classes

Methods

doc_str

def doc_str(self) -> str

Create documents from its contents.

Returns

  • str: Created from docstrings and annotations.

Functions

is_var

def is_var(obj: object) -> bool

Utility for filtering unexpected objects.