DOCSEARCHbyAlgolia
Submit Docs

lazydocs

repository·main·Indexed 42 days ago

https://github.com/ml-tooling/lazydocs

A tool for generating Markdown API documentation from Python code using Google-style docstrings. It features a CLI and a programmatic API via the MarkdownGenerator class and generate_docs function, allowing for easy integration into GitHub or MkDocs sites. Supports source code linking with --src-base-url, docstring validation via pydocstyle, and output formats including md and mdx.

Tokens
3.6K
Snippets
14
Records
20
Agent score
51%

What's inside lazydocs

  1. API Overview for lazydocs

    main

    lazydocs provides tools for generating Markdown documentation from Python source code. The primary functionality is located in the lazydocs.generation module, which handles the conversion of Google-style docstrings into structured Markdown files.

    Key components include:

    • lazydocs.generation.MarkdownGenerator: The core class used to manage the documentation generation process.
    • lazydocs.generation.generate_docs: A high-level function to generate documentation for specific file paths.
    • lazydocs.generation.to_md_file: A utility function to convert provided text into an API documentation file.

  2. Integrate lazydocs with MkDocs

    main

    To integrate generated documentation into an MkDocs site, follow these steps:

    1. Generate documentation into a subfolder of your MkDocs directory (e.g., api-docs). It is highly recommended to use --overview-file and --src-base-url so that source-code links work correctly.
      lazydocs \
    --output-path="./docs/api-docs" \
    --overview-file="README.md" \
    --src-base-url="https://github.com/example/my-project/blob/main/" \
    my_package
    2. Use the awesome-pages plugin: Install mkdocs-awesome-pages-plugin via pip and add it to your mkdocs.yaml. This allows MkDocs to automatically discover the generated markdown files.
    3. Configure navigation: If you used --overview-file, a .pages file is automatically created. Alternatively, you can manually create a .pages file in your api-docs folder to define the structure:
      title: API Reference
nav:
   - Overview: README.md
   - ...

  3. Validate docstrings with `--validate`

    main

    Lazydocs requires valid Google-style docstrings. To ensure your documentation generation doesn't fail due to formatting issues, use the --validate flag. This runs pydocstyle on your docstrings and cancels the generation process if any issues are found.

    Note: This requires pydocstyle to be installed in your environment.

    Example:

    lazydocs --validate my_package

  4. Generate Markdown API documentation via CLI

    main

    To generate Markdown-based API documentation for a Python project, use the lazydocs command followed by the path to your package, a specific script, or module/class/function imports.

    By default, documentation is generated in the ./docs folder of your working directory.

    Examples:

    Generate docs for a package folder:

    lazydocs path/to/your/package

    Generate docs for a specific class import:

    lazydocs my_package.AwesomeClass

  7. Generate an API overview file

    main

    For large projects with many modules, classes, and functions, you can generate a high-level API overview. Use the --overview-file option to specify the filename for this markdown overview.

    Example:

    lazydocs --overview-file="README.md" my_package

  8. Configure source code linking with `--src-base-url`

    main

    Lazydocs can insert badges in the documentation that link directly to the source code file and line number.

    If your documentation is hosted outside of the GitHub repository where the code lives, you must set the --src-base-url option. This URL acts as a prefix for all source-code links.

    Example:

    lazydocs --src-base-url="https://github.com/example/my-project/blob/main/" my_package

  9. Use `MarkdownGenerator` for granular documentation control

    main

    The MarkdownGenerator class provides fine-grained control over converting specific Python objects into markdown strings. This is useful when you want to build custom documentation workflows rather than using the bulk generate_docs function.

    Initialization:

    from lazydocs.generation import MarkdownGenerator

generator = MarkdownGenerator(
    src_root_path='/path/to/src',
    src_base_url='https://github.com/user/repo/blob/main/',
    remove_package_prefix=True,
    url_line_prefix='L'
)

    Available Methods:

    • module2md(module, ...): Converts an imported module into a markdown string containing its functions and classes.
    • import2md(obj, ...): Generates markdown for a specific object or import.
    • class2md(cls, ...): Generates markdown for a specific class, including its methods and variables.
    • func2md(func, ...): Generates markdown for a specific function or method.
    • toc2md(module, ...): Generates a Table of Contents for an imported object.
    • overview2md(...): Generates a documentation overview string.
    from lazydocs.generation import MarkdownGenerator
import my_module

generator = MarkdownGenerator(src_base_url='https://github.com/user/repo/blob/main/')

# Generate markdown for a whole module
module_md = generator.module2md(my_module)

# Generate markdown for a specific class within that module
class_md = generator.class2md(my_module.MyClass)

  10. Generate documentation using `generate_docs`

    main

    The generate_docs function is the primary entry point for generating full markdown documentation for one or more paths (files or import names) based on Google-style docstrings.

    Key Parameters:

    • paths: A list of strings representing the paths or import names to document.
    • output_path: Where to save the files. Use 'stdout' to print the markdown to the console instead of writing to disk.
    • src_root_path: The root directory of your source code (defaults to git repo root).
    • src_base_url: The base URL for GitHub links (e.g., https://github.com/user/repo/blob/main/). This is used to generate source code line anchors.
    • validate: If True, it validates docstrings using pydocstyle (requires pydocstyle to be installed).
    • overview_file: If provided, generates an overview file with this name.
    • include_toc: If True, includes a Table of Contents in the generated files.
    from lazydocs.generation import generate_docs

generate_docs(
    paths=['my_package.my_module'],
    output_path='./docs',
    src_base_url='https://github.com/user/repo/blob/main/',
    validate=True,
    include_toc=True
)

  11. Generate documentation with generate_docs

    main
    Use the lazydocs.generation.generate_docs function to automatically create Markdown documentation for your Python modules. This function parses your code and generates documentation based on Google-style docstrings.

  12. Programmatic API: generate_docs

    main

    To programmatically generate all markdown documentation files, use the generate_docs function. The parameters for this function correspond to the CLI options.

    Example:

    from lazydocs import generate_docs

# Generate docs for 'my_module' into the './docs' folder
generate_docs(["my_module"], output_path="./docs")
    from lazydocs import generate_docs

# The parameters of this function correspond to the CLI options
generate_docs(["my_module"], output_path="./docs")