ClammingPy - Light Python-API Documentation in Markdown and HTML

Overview

ClammingPy is an open-source library useful to export a Python class into
a Markdown or HTML file, for documentation purpose. ClammingPy 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 ClammingPy

ClammingPy requires Whakerexa to be installed; it can be downloaded from:
https://whakerexa.sf.net. Unpack it into the ClammingPy package.

From the repo:

Download the repository and unpack it. ClammingPy tool includes the following folders and files:

1. clamming: the source code of ClammingPy 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 ClammingPy documentation, using clamming library
6. etc: etcetera!

From the 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 ClammingPy 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 ClammingPy 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 = 'ClammingPy ' + 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.wexa_statics = '../Whakerexa-0.2/wexa_statics'
>>> html_export.software = 'ClammingPy ' + 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 ClammingPy documentation in docs folder for extended usages.

Projects using ClammingPy

• WhakerPy: https://whakerpy.sf.net
• AudiooPy: https://audioopy.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.