Clamming - Light Python-API Documentation in Markdown and HTML

Overview

Clamming is an open-source library useful to export a Python class into a Markdown or HTML file, for documentation purpose. Clamming mainly supports reStructured format, however, docstrings are analyzed with flexibility rather than completeness...

Both ReST and Epydoc field styles are supported. It means that either :field: or @field: can be used indifferently, with upper- or lower- cases.

Two very useful non-standard "field list" items are added: :example: and :code:. Finally, some variants in field names are supported:

• :return: or :returns: are both interpreted the same way;
• :raise: or :raises: or :catch: or :except: are all interpreted the same way.

Notice that we expect to generate HTML-5 with a high level of WCAG 2.1 conformity.

Install Clamming

Clamming requires "wexa_statics" to be installed; it can be downloaded from: https://whakerexa.sf.net. It is already included into the "docs" folder.

From clamming repo:

Download the repository and unpack it. Clamming package includes the following folders and files:

1. clamming: the source code of Clamming library
2. docs: the documentation of clamming library in HTML, already including "wexa_statics".
3. tests: unittest of Clamming library
4. sample: a sample class Vehicle to illustrate clamming use
5. makedoc.py: create the Clamming documentation, using Clamming library
6. etc: etcetera!

From clamming package:

Install it in your python environment from the local wheel with:

> python -m pip install dist/<clamming.whl>

License

This is the implementation of the Clamming library, under the terms of the GNU General Public License version 3.

Usage

Documenting a single class

The sample folder contains a Python class example and the simplest solution to get access to the documentation either in Markdown or HTML. The Vehicle class is illustrating the supported format and its flexibility. Try it with:

> cd sample
> python makedoc_vehicle.py > vehicle.html
> python makedoc_vehicle.py --md > vehicle.md

or with the main program:

> python main.py -c Vehicle -m sample.vehicle
> python main.py -c Vehicle -m sample.vehicle --md

In the same way, the documentation of any Python class can be extracted with, for example:

> python main.py -c TestCase -m unittest --md
> python main.py -c BaseHTTPRequestHandler -m http.server --md

When using the Clamming library directly, the documented files can be obtained with the following Python code:

>>> import clamming
>>> import Vehicle  # Or any other Python class to be documented
>>> parser = clamming.ClammingClassParser(Vehicle)
>>> clams = clamming.ClamsClass(parser)
>>> print(clams.html())
>>> print(clams.markdown())

Documenting all classes of a package

Below are two examples with the main program:

> python main.py -m clamming > clamming.html
> python main.py -m http.server --md | grep "### Class "
### Class `HTTPServer`
### Class `ThreadingHTTPServer`
### Class `BaseHTTPRequestHandler`
### Class `SimpleHTTPRequestHandler`
### Class `CGIHTTPRequestHandler`

The following Python code allows to generate the documentation of clamming module in Mardown format or in HTML format as a standalone content:

>>> import clamming
>>> clams_pack = clamming.ClamsPack(clamming)
>>> print(clams_pack.markdown())
>>> print(clams_pack.html())

Here is a summary of the main steps to generate an HTML documentation, in a bunch of HTML files:

>>> import clamming
>>> # Options for HTML exportation
>>> html_export = clamming.HTMLDocExport()
>>> html_export.software = 'Clamming ' + clamming.__version__
>>> # Create an HTML page for each class of the module
>>> clams_pack = clamming.ClamsPack(clamming)
>>> clams_pack.html_export_clams("docs", html_export)

Documenting all classes of a list of packages

There is an all-in-one function to generate the HTML documentation of a list of packages. It requires to define the followings:

1. The list of ClamsPack instances of the modules to be documented;
2. The HTMLDocExport allowing to fix the HTML options for files exportation.

>>> import clamming
>>> # List of modules to be documented.
>>> packages = list()
>>> packages.append(clamming.ClamsPack(clamming))
>>> # Options for HTML exportation
>>> html_export = clamming.HTMLDocExport()
>>> html_export.software = 'Clamming ' + clamming.__version__
>>> # Export documentation to HTML files into the "docs" folder.
>>> clamming.ClamsPack.html_export_packages(packages, "docs", html_export)
>>> # Export documentation to Markdown files into the "docs" folder.
>>> clamming.ClamsPack.markdown_export_packages(packages, "docs", html_export)

See makedoc.py Python script for details.

See the Clamming documentation in docs folder for extended usages.

Projects using Clamming

• WhakerPy: https://whakerpy.sf.net
• PyMancala: https://pymancala.sf.net
• SPPAS: https://sppas.org
• contact the author if you want to add a project here

Author/Copyright

Copyright (C) 2023-2024 - Brigitte Bigi - contact@sppas.org, Laboratoire Parole et Langage, Aix-en-Provence, France.