[Distutils] More documentation for setup meta-data

[Richard Jones]

I'm trying to better document the meta-data for the distutils (and hence 
PyPI). I've added words to the section in the dev doc about meta-data, and 
would like some feedback before I post the patch to be applied. Sorry, it's 
in LaTeX form (until someone writes the ReST->python doc converter ;)

\subsection{Additional meta-data}
\label{meta-data}

The setup script may include additional meta-data beyond the name and
version. This information includes:

\begin{tableiii}{l|l|l|c}{code}%
  {Meta-Data}{Description}{Value}{Notes}
  \lineiii{name}{the name of the package}{short string}{(1)}
  \lineiii{version}{the version of this release}{short string}{(1)(4)}
  \lineiii{author}{package author's name}{short string}{(2)}
  \lineiii{author_email}{email address of the package author}{email 
address}{(2)}
  \lineiii{maintainer}{package maintainer's name}{short string}{(2)}
  \lineiii{maintainer_email}{email address of the package maintainer}{email 
address}{(2)}
  \lineiii{home_page}{the location of the homepage for the package}{URL}{(1)}
  \lineiii{description}{a short, summary description of the package}{short 
string}{}
  \lineiii{long_description}{a longer description of the package}{long 
string}{}
  \lineiii{download_url}{a location where the package may be 
downloaded}{URL}{(3)}
  \lineiii{classifiers}{a list of Trove classifiers}{list of strings}{(3)}
\end{tableiii}

\noindent Notes:
\begin{description}
\item[(1)] these fields are required
\item[(2)] either the author or the maintainer must be nominated
\item[(3)] should not be used if your package is to be compatible with
  Python versions prior to 2.2.3 or 2.3. The list is available from the
  PyPI website.
\item[(4)] it is recommended that versions take the form
           <major>.<minor>.<patch>[.<sub>]
\item["short string"] a single line of text, not more than 200 characters
\item["long string"] multiple lines of text
\item["list of strings"] see below
\end{description}

\option{version} encoding is an art in itself. Python packages generally
adhere to the version format \em{major.minor.patch}. The major number is
0 for initial, experimental releases of software. It is incremented for
releases that represent major milestones in a package. The minor number is
incremented when important new features are added to the package. The patch
number increments when bug-fix releases are made. Additional trailing
version information is sometimes used to indicate sub-releases.
These are "a1,a2,...,aN" (for alpha releases, where 
functionality and API may change), "b1,b2,...,bN" (for beta releases, which
only fix bugs) and "pr1,pr2,...,prN" (for final pre-release release
testing). Some examples:

\begin{description}
\item[0.1.0] the first, experimental release of a package
\item[1.0.1a2] the second alpha release of the first patch version of 1.0
\end{description}

\option{classifiers} are specified in a python list:

\begin{verbatim}
setup(...
        classifiers = [
            'Development Status :: 4 - Beta',
            'Environment :: Console',
            'Environment :: Web Environment',
            'Intended Audience :: End Users/Desktop',
            'Intended Audience :: Developers',
            'Intended Audience :: System Administrators',
            'License :: OSI Approved :: Python Software Foundation License',
            'Operating System :: MacOS :: MacOS X',
            'Operating System :: Microsoft :: Windows',
            'Operating System :: POSIX',
            'Programming Language :: Python',
            'Topic :: Communications :: Email',
            'Topic :: Office/Business',
            'Topic :: Software Development :: Bug Tracking',
        ],
      ...
)
\end{verbatim}

If you wish to include classifiers in your \file{setup.py} file and also
wish to remain backwards-compatible with Python releases prior to 2.2.3,
then you can include the following code fragment in your \file{setup.py}
before the \code{setup()} call.

\begin{verbatim}
# patch distutils if it can't cope with the "classifiers" or 
# "download_url" keywords
if sys.version < '2.2.3':
    from distutils.dist import DistributionMetadata
    DistributionMetadata.classifiers = None
    DistributionMetadata.download_url = None
\end{verbatim}