API

This is the API documentation of Debmans. It should be stable across major releases. See the Design document for more details about the design.

Todo

the click module decorators make all the click.command() functions hidden from Sphinx. This is presumably because the signature changes from a func to a cls, but remains to be confirmed.

Extractor

The extractor processes Debian packages and extracts specific patterns into a target directory. It uses a cache file that is named according to the package name and version to avoid the costly operation of opening the same package file multiple times.

Renderer

The Renderer module takes care of turning extracted documentation into HTML format. It uses Jinja templates and simple timestamp-based caching.

Main entry point

The main entry point of debmans is in the debmans.__main__ module. This is to make it possible to call debmans directly from the source code through the Python interpreter with:

python -m debmans

All this code is here rather than in __init__.py to avoid requiring too many dependencies in the base module, which contains useful metadata for setup.py.

This uses the click module to define the base command and options, which then get passed to subcommands through the obj parameter, see pass_obj in the click documentation.

Logger

This is a simple helper module to configure the logging module consistently.

debmans.logger.setup_logging(name='debmans', level='info', syslog=False, stream=None)

setup logging module according to the arguments provided

Utilities

Those are various utilities reused in multiple modules that did not fit anywhere else.

various utilities for debmans

debmans.utils.find_parent_module()

find the name of a the first module calling this module

if we cannot find it, we return the current module’s name (__name__) instead.

debmans.utils.find_static_file(path)

locate a file in the distribution

this will look in the shipped files in the package

this assumes the files are at the root of the package or the source tree (if not packaged)

this does not check if the file actually exists.

Parameters:path (str) – path for the file, relative to the source tree root Returns:the absolute path to the file

debmans.utils.mkdirp(path)

make directories without error

this is a simple wrapper around os.makedirs() to avoid failing if the directory already exists.

it also logs to the DEBUG logging facility when a directory is created.