python-manpage/README

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 :