python-apibook

GitHub deploymentsPyPI - Version

Are you tired of fighting Sphinx to get it to do what you want? Do you want to write your documentation in Markdown? Do you want to easily combine prose with API docs? Then this is the tool for you!

python-apibook uses the AST module to parse your code and generate API documentation in Markdown format, and can easily be merged into your existing mdbook SUMMARY.md file.

Installation

pip install git+https://github.com/tgolsson/python-apibook.git

Usage

To see the available options, run:

python -m apibook.cli --help

To generate API documentation for a package, run:

python-apibook my_package doc/src --summary-template-file doc/SUMMARY.tmpl

This will generate all markdown sources and a SUMMARY.md file in the doc/src directory, which you can include in your mdbook project. Hint: Combine this with mdbook serve doc to see the results in real-time.

package apibook

python-apibook is a tool that generates markdown documentation directly from your Python source code.

It uses the ast module to parse your code and extract docstrings, and then writes the documentation to markdown files. While using the ast for parsing comes with a lot of limitations, it also means no code is executed, and no dependencies have to be installed. This makes python-apibook very lightweight and easy to use.

The goal of the tool is to integrate seamlessly into your existing mdbook documentation, but you can provide a custom summary template if you want to use another system.

module apibook.cli

Main entrypoint for the CLI usage.

This module provides a command line interface for the apibook package. The CLI accepts the following arguments:

  • root_dir: the root directory to search for Python files
  • output_dir: the output directory for markdown files
  • summary_template_file: Optional path to a file containing a summary template.

Example usage:

python -m apibook.cli my_package/ doc/src --summary-template-file doc/SUMMARY.tmpl

Running the above command will generate markdown files for all Python files in the my_package, and write them to the doc/src directory. The SUMMARY.md file will be generated using the template found in doc/SUMMARY.tmpl.

An example template file might look like this:

# SUMMARY

[Introduction](README.md)

# Usage

- [Quickstart](quickstart.md)
- [Advanced Usage](advanced.md)

# API Reference

{{apibook_toc}}

Functions

def main() -> None

Classes

class Args:

Class to hold command line arguments.

Fields

  • root_dir: str

  • output_dir: str

  • summary_template_file: str | None = None

  • verbose: bool = False

Methods

def parse() -> Args

Parse command line arguments.

module apibook.data

Classes

class Arg:

Information about a function argument.

Fields

  • name: str

  • type: str

  • default: str | None = None

  • docstring: str = None

class Signature:

Class to hold signature information for a function or method. Might also be used to hold information about a class constructor, even if those are defined on the class itself.

Fields

  • args: list

  • returns: list

  • docstring: str

class Decorator:

Class to hold decorator information for a class or function.

Fields

  • name: str

  • args: list

  • kwargs: dict

  • is_call: bool = False

  • is_property: bool = False

class Class:

Class to hold class information.

Fields

  • name: str

  • bases: list

  • decorators: list

  • methods: list

  • fields: list

  • docstring: str

Methods

def to_md(self) -> None

Convert class to markdown.

class Method:

Class to hold method information.

Fields

  • name: str

  • args: list

  • kwonlyargs: list

  • returns: str

  • docstring: str

Methods

def to_md(self, is_method, extra_signature) -> None

Convert method to markdown.

Arguments:

  • is_method
  • extra_signature(Signature)

class Module:

Class to hold module information.

Fields

  • name: str

  • docstring: str

  • classes: list

  • functions: list

  • variables: list

  • aliases: list

  • all_exports: list

  • imports: list

Methods

def resolve_export(self, item) -> str

Resolve an export to a module + item.

Arguments:

  • item
def resolve_import(self, item) -> (str, str)

Resolve an import to a module + item.

Arguments:

  • item(str): the item to resolve

Returns:

  • the module containing the item the item queried
def to_md(self) -> None

Convert module to markdown.

class NakedImport:

Fields

  • module: str

Methods

def to_md(self) -> None

class FromImport:

Fields

  • module: str

  • names: list

  • relative: int

Methods

def to_md(self) -> None

class TypeAlias:

Fields

  • name: str

  • type: str

Methods

def to_md(self) -> None

class ClassField:

Fields

  • name: str

  • type: str

  • default: str | None

class Variable:

Fields

  • name: str

  • value: str

module apibook.main

Generates markdown from Python docstrings.

Functions

def root_module(root) -> str

Get the root module name from a path.

Arguments:

  • root(str): the root path

Returns:

  • the root module name
def path_to_module(root, file) -> str

Convert a path to a module name.

Arguments:

  • root(str): the parent directory of the file
  • file(str): the module name

Returns:

  • the dotted module name
def fixup_reexports(root_module, docs) -> None

Inlines items that are reexported from other modules via 'all' lists.

Arguments:

  • root_module(str)
  • docs(dict[str, Module])
def run(root_dir, output_dir, summary_output_template) -> None

Run the docstring generator.

Arguments:

  • root_dir(str)
  • output_dir(str)
  • summary_output_template(str | None)