Manual page library for Python
The standard Unix manual system is structured into documents, each
called a “manual page” (or “man page”). This library helps you to
generate these documents from Python code.
* Python API for generating Unix manual page documents.
* Integration with the `argparse.ArgumentParser` class for each
command, to create a manual page document for the command.
* Integration with the Setuptools build system, to generate manual
page documents when building the distribution.
* Python 3.3 or later.
While the Unix manual page system is a common standard, too many
Python packages install commands, libraries, and file formats without
any Unix manual pages.
Legacy markup language
A manual page document is written in `troff`_, which is a text markup
language. In the 21st century, almost nobody uses troff anymore
*except* for writing Unix manual page documents, and there is a lack
of experience in using the language well.
So it's hard to find well-formatted manual pages, and many such pages
do not conform to markup conventions for the system.
The `manpage` library provides ways to generate Unix man pages,
without any need to learn any troff.
.. _troff: http://www.troff.org/
Avoid duplicate documentation
A good manual page document has a structure and contains significant
information; it is not just a terse listing of command options.
Neither is it a full end-user treatise or tutorial. Instead, it should
be a concise reference work, in a standard format.
Some parts of the manual page should be written specifically for that
document. Others, though, can be automatically gathered from text
So it's hard to find well-written or complete manual pages, and many
busy developers postpone writing them at all.
The `manpage` library has various sensible defaults for a document's
meta-data. It can also populate larger parts of the document from
existing text in the Python code.
Copying this work
Copyright © 2016 Ben Finney .
This is free software: you may copy, modify, and/or distribute this work
under the terms of the GNU General Public License as published by the
Free Software Foundation; version 3 of that license or any later version.
No warranty expressed or implied. See the file ‘LICENSE.GPL-3’ for details,
or view it online at .
vim: fileencoding=utf-8 filetype=rst :