1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192 |
- 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.
- Features
- ========
- * 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.
- Requirements
- ============
- * Python 3.3 or later.
- Motivation
- ==========
- 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
- written elsewhere.
- 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 <ben+python@benfinney.id.au>.
- 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 <URL:https://www.gnu.org/licenses/gpl-3.0.html>.
- ..
- Local variables:
- coding: utf-8
- mode: text
- mode: rst
- End:
- vim: fileencoding=utf-8 filetype=rst :
|