Skip to content

Files

Latest commit

 

History

History
293 lines (181 loc) · 8.79 KB

lazydocs.generation.md

File metadata and controls

293 lines (181 loc) · 8.79 KB

module lazydocs.generation

Main module for markdown generation.

Table of Contents

function to_md_file

to_md_file(
    markdown_str: str,
    filename: str,
    out_path: str = '.',
    watermark: bool = True,
    disable_markdownlint: bool = True,
    is_mdx: bool = False
) → None

Creates an API docs file from a provided text.

Args:

  • markdown_str (str): Markdown string with line breaks to write to file.
  • filename (str): Filename without the .md
  • out_path (str): The output directory.
  • watermark (bool): If True, add a watermark with a timestamp to bottom of the markdown files.
  • disable_markdownlint (bool): If True, an inline tag is added to disable markdownlint for this file.
  • is_mdx (bool, optional): JSX support. Default to False.

function generate_docs

generate_docs(
    paths: List[str],
    output_path: str = './docs',
    src_root_path: Optional[str] = None,
    src_base_url: Optional[str] = None,
    remove_package_prefix: bool = False,
    ignored_modules: Optional[List[str]] = None,
    output_format: Optional[str] = None,
    overview_file: Optional[str] = None,
    watermark: bool = True,
    validate: bool = False,
    private_modules: bool = False,
    include_toc: bool = False,
    url_line_prefix: Optional[str] = None
) → None

Generates markdown documentation for provided paths based on Google-style docstrings.

Args:

  • paths: Selected paths or import name for markdown generation.
  • output_path: The output path for the creation of the markdown files. Set this to stdout to print all markdown to stdout.
  • src_root_path: The root folder name containing all the sources. Fallback to git repo root.
  • src_base_url: The base url of the github link. Should include branch name. All source links are generated with this prefix.
  • remove_package_prefix: If True, the package prefix will be removed from all functions and methods.
  • ignored_modules: A list of modules that should be ignored.
  • output_format: Markdown file extension and format.
  • overview_file: Filename of overview file. If not provided, no overview file will be generated.
  • watermark: If True, add a watermark with a timestamp to bottom of the markdown files.
  • validate: If True, validate the docstrings via pydocstyle. Requires pydocstyle to be installed.
  • private_modules: If True, includes modules with _ prefix.
  • url_line_prefix: Line prefix for git repository line url anchors. Default: None - github "L".

class MarkdownGenerator

Markdown generator class.

constructor __init__

MarkdownGenerator(
    src_root_path: Optional[str] = None,
    src_base_url: Optional[str] = None,
    remove_package_prefix: bool = False,
    url_line_prefix: Optional[str] = None
)

Initializes the markdown API generator.

Args:

  • src_root_path: The root folder name containing all the sources.
  • src_base_url: The base github link. Should include branch name. All source links are generated with this prefix.
  • remove_package_prefix: If True, the package prefix will be removed from all functions and methods.
  • url_line_prefix: Line prefix for git repository line url anchors. Default: None - github "L".

method class2md

class2md(cls: Any, depth: int = 2, is_mdx: bool = False) → str

Takes a class and creates markdown text to document its methods and variables.

Args:

  • cls (class): Selected class for markdown generation.
  • depth (int, optional): Number of # to append to function name. Defaults to 2.
  • is_mdx (bool, optional): JSX support. Default to False.

Returns:

  • str: Markdown documentation for selected class.

method func2md

func2md(
    func: Callable,
    clsname: str = '',
    depth: int = 3,
    is_mdx: bool = False
) → str

Takes a function (or method) and generates markdown docs.

Args:

  • func (Callable): Selected function (or method) for markdown generation.
  • clsname (str, optional): Class name to prepend to funcname. Defaults to "".
  • depth (int, optional): Number of # to append to class name. Defaults to 3.
  • is_mdx (bool, optional): JSX support. Default to False.

Returns:

  • str: Markdown documentation for selected function.

method import2md

import2md(
    obj: Any,
    depth: int = 1,
    is_mdx: bool = False,
    include_toc: bool = False
) → str

Generates markdown documentation for a selected object/import.

Args:

  • obj (Any): Selcted object for markdown docs generation.
  • depth (int, optional): Number of # to append before heading. Defaults to 1.
  • is_mdx (bool, optional): JSX support. Default to False.
  • include_toc (bool, Optional): Include table of contents for module file. Defaults to False.

Returns:

  • str: Markdown documentation of selected object.

method module2md

module2md(
    module: module,
    depth: int = 1,
    is_mdx: bool = False,
    include_toc: bool = False
) → str

Takes an imported module object and create a Markdown string containing functions and classes.

Args:

  • module (types.ModuleType): Selected module for markdown generation.
  • depth (int, optional): Number of # to append before module heading. Defaults to 1.
  • is_mdx (bool, optional): JSX support. Default to False.
  • include_toc (bool, optional): Include table of contents in module file. Defaults to False.

Returns:

  • str: Markdown documentation for selected module.

method overview2md

overview2md(is_mdx: bool = False) → str

Generates a documentation overview file based on the generated docs.

Args:

  • is_mdx (bool, optional): JSX support. Default to False.

Returns:

  • str: Markdown documentation of overview file.

method toc2md

toc2md(module: module = None, is_mdx: bool = False) → str

Generates table of contents for imported object.

This file was automatically generated via lazydocs.