Light Python-API Documentation in Markdown and HTML
Project description
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:
clamming
: the source code ofClamming
librarydocs
: the documentation of clamming library in HTML, already including "wexa_statics".tests
: unittest ofClamming
librarysample
: a sample classVehicle
to illustrateclamming
usemakedoc.py
: create the Clamming documentation, using Clamming libraryetc
: 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:
- The list of ClamsPack instances of the modules to be documented;
- 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.