ClammingPy is a Light Python-API Documentation in Markdown and HTML
You have a Python API you documented with docstrings, and you want to share documentation in either Markdown or HTML.
ClammingPy is the documentation generator you may need: it is generating Markdown or HTML from the docstrings within the source code of any Python library.
ClammingPy generates HTML-5 with a high level of WCAG 2.1 conformity.
Python modules are usually documented using docstrings. They typically use plain text markup formats such as reStructuredText (reST, the markup used for writing the official Python documentation) and/or Markdown.
ClammingPy
is a Python, free, open-source, self-hosted library to export a Python class or module into a Markdown and/or HTML files, for documentation purpose. Contrariwise to other documentation tools, 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 reST non-standard field items can also be used in the docstrings: :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.Get it here: https://sourceforge.net/projects/clamming/.
ClammingPy requires Whakerexa to be installed; it can be downloaded from: https://whakerexa.sf.net. Get its documentation here: https://whakerexa.sourceforge.io.
Unpack it into the ClammingPy/docs
folder.
Download the repository and unpack it. ClammingPy tool includes the following folders and files:
clamming
: the source code of ClammingPy
librarydocs
: the documentation of clamming library in HTML, already including "wexa_statics".tests
: unittest of Clamming
librarysample
: a sample class Vehicle
to illustrate clamming
usemakedoc.py
: create the ClammingPy documentation, using clamming
libraryetc
: etcetera!Install it in your python environment from the local wheel with:
> python -m pip install dist/<clamming.whl>
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())
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.ExportOptions()
>> > 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)
There is an all-in-one function to generate the HTML documentation of a list of packages. It requires to define the followings:
>> > import clamming
>> > # List of modules to be documented.
>> > packages = list()
>> > packages.append(clamming)
>> > # Options for HTML exportation
>> > html_export = clamming.ExportOptions()
>> > html_export.wexa_statics = '../Whakerexa-0.4/wexa_statics'
>> > html_export.software = 'ClammingPy ' + clamming.__version__
>> > # Export documentation to HTML files into the "docs" folder.
>> > m = clamming.ClamsModules(packages)
>> > m.html_export_packages("docs", html_export)
>> > # Export documentation to Markdown files into the "docs" folder.
>> > m.markdown_export_packages("docs")
See makedoc.py
Python script for details.
See the ClammingPy documentation in
docs
folder for extended usages.
If you plan to contribute to the code or to report a bug, please send an e-mail to the author.
Any and all constructive comments are welcome.
See the accompanying LICENSE and AUTHORS files for the full list of contributors.
Copyright (C) 2023-2024 - Brigitte Bigi - contact@sppas.org
Laboratoire Parole et Langage, Aix-en-Provence, France
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see https://www.gnu.org/licenses/.