Add more documentation
Moved a good portion of README into the sphinx docs. Also started fleshing out descriptions of how to use things. Also, fix the sphinx config. Change-Id: If53dcdaea0a48ef613e3097ab55d34f056160188
This commit is contained in:
parent
c84876dc0f
commit
904f79c867
121
README.rst
121
README.rst
|
@ -22,127 +22,6 @@ when that library itself will alter how the setup is processed. As Metadata
|
|||
2.0 and other modern Python packaging PEPs come out, `pbr` aims to support
|
||||
them as quickly as possible.
|
||||
|
||||
`pbr` reads and then filters the `setup.cfg` data through a setup hook to
|
||||
fill in default values and provide more sensible behaviors, and then feeds
|
||||
the results in as the arguments to a call to `setup.py` - so the heavy
|
||||
lifting of handling python packaging needs is still being done by
|
||||
`setuptools`.
|
||||
|
||||
Behaviors
|
||||
=========
|
||||
|
||||
What It Does
|
||||
------------
|
||||
|
||||
PBR can and does do a bunch of things for you:
|
||||
|
||||
* **Version**: Manage version number bad on git revisions and tags
|
||||
* **AUTHORS**: Generate AUTHORS file from git log
|
||||
* **ChangeLog**: Generate ChangeLog from git log
|
||||
* **Sphinx Autodoc**: Generate autodoc stub files for your whole module
|
||||
* **Requirements**: Store your dependencies in a pip requirements file
|
||||
* **long_description**: Use your README file as a long_description
|
||||
* **Smart find_packages**: Smartly find packages under your root package
|
||||
|
||||
Version
|
||||
^^^^^^^
|
||||
|
||||
Version strings will be inferred from git. If a given revision is tagged,
|
||||
that's the version. If it's not, and you don't provide a version, the version
|
||||
will be very similar to git describe. If you do, then we'll assume that's the
|
||||
version you are working towards, and will generate alpha version strings
|
||||
based on commits since last tag and the current git sha.
|
||||
|
||||
AUTHORS and ChangeLog
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Why keep an AUTHORS or a ChangeLog file, when git already has all of the
|
||||
information you need. AUTHORS generation supports filtering/combining based
|
||||
on a standard .mailmap file.
|
||||
|
||||
Sphinx Autodoc
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Sphinx can produce auto documentation indexes based on signatures and
|
||||
docstrings of your project- but you have to give it index files to tell it
|
||||
to autodoc each module. That's kind of repetitive and boring. PBR will
|
||||
scan your project, find all of your modules, and generate all of the stub
|
||||
files for you.
|
||||
|
||||
Sphinx documentation setups are altered to generate man pages by default. They
|
||||
also have several pieces of information that are known to setup.py injected
|
||||
into the sphinx config.
|
||||
|
||||
Requirements
|
||||
^^^^^^^^^^^^
|
||||
|
||||
You may not have noticed, but there are differences in how pip
|
||||
requirements.txt files work and how distutils wants to be told about
|
||||
requirements. The pip way is nicer, because it sure does make it easier to
|
||||
popuplate a virtualenv for testing, or to just install everything you need.
|
||||
Duplicating the information, though, is super lame. So PBR will let you
|
||||
keep requirements.txt format files around describing the requirements for
|
||||
your project, will parse them and split them up approprirately, and inject
|
||||
them into the install_requires and/or tests_require and/or dependency_links
|
||||
arguments to setup. Voila!
|
||||
|
||||
long_description
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
There is no need to maintain two long descriptions- and your README file is
|
||||
probably a good long_description. So we'll just inject the contents of your
|
||||
README.rst, README.txt or README file into your empty long_description. Yay
|
||||
for you.
|
||||
|
||||
Usage
|
||||
=====
|
||||
pbr requires a distribution to use distribute. Your distribution
|
||||
must include a distutils2-like setup.cfg file, and a minimal setup.py script.
|
||||
|
||||
A simple sample can be found in pbr s own setup.cfg
|
||||
(it uses its own machinery to install itself)::
|
||||
|
||||
[metadata]
|
||||
name = pbr
|
||||
author = OpenStack Foundation
|
||||
author-email = openstack-dev@lists.openstack.org
|
||||
summary = OpenStack's setup automation in a reuable form
|
||||
description-file = README
|
||||
license = Apache-2
|
||||
classifier =
|
||||
Development Status :: 4 - Beta
|
||||
Environment :: Console
|
||||
Environment :: OpenStack
|
||||
Intended Audience :: Developers
|
||||
Intended Audience :: Information Technology
|
||||
License :: OSI Approved :: Apache Software License
|
||||
Operating System :: OS Independent
|
||||
Programming Language :: Python
|
||||
keywords =
|
||||
setup
|
||||
distutils
|
||||
[files]
|
||||
packages =
|
||||
oslo
|
||||
|
||||
The minimal setup.py should look something like this::
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from setuptools import setup
|
||||
|
||||
setup(
|
||||
setup_requires=['pbr'],
|
||||
pbr=True,
|
||||
)
|
||||
|
||||
Note that it's important to specify `pbr=True` or else the pbr functionality
|
||||
will not be enabled.
|
||||
|
||||
It should also work fine if additional arguments are passed to `setup()`,
|
||||
but it should be noted that they will be clobbered by any options in the
|
||||
setup.cfg file.
|
||||
|
||||
Running Tests
|
||||
=============
|
||||
The testing system is based on a combination of tox and testr. The canonical
|
||||
|
|
|
@ -1,9 +1,189 @@
|
|||
pbr - Python Build Reasonableness
|
||||
=================================
|
||||
===================================
|
||||
pbr - Python Build Reasonableness
|
||||
===================================
|
||||
|
||||
A library for managing setuptools packaging needs in a consistent manner.
|
||||
|
||||
PBR is not a library about beer.
|
||||
`pbr` reads and then filters the `setup.cfg` data through a setup hook to
|
||||
fill in default values and provide more sensible behaviors, and then feeds
|
||||
the results in as the arguments to a call to `setup.py` - so the heavy
|
||||
lifting of handling python packaging needs is still being done by
|
||||
`setuptools`.
|
||||
|
||||
What It Does
|
||||
============
|
||||
|
||||
PBR can and does do a bunch of things for you:
|
||||
|
||||
* **Version**: Manage version number based on git revisions and tags
|
||||
* **AUTHORS**: Generate AUTHORS file from git log
|
||||
* **ChangeLog**: Generate ChangeLog from git log
|
||||
* **Sphinx Autodoc**: Generate autodoc stub files for your whole module
|
||||
* **Requirements**: Store your dependencies in a pip requirements file
|
||||
* **long_description**: Use your README file as a long_description
|
||||
* **Smart find_packages**: Smartly find packages under your root package
|
||||
|
||||
Version
|
||||
-------
|
||||
|
||||
Version strings will be inferred from git. If a given revision is tagged,
|
||||
that's the version. If it's not, and you don't provide a version, the version
|
||||
will be very similar to git describe. If you do, then we'll assume that's the
|
||||
version you are working towards, and will generate alpha version strings
|
||||
based on commits since last tag and the current git sha.
|
||||
|
||||
AUTHORS and ChangeLog
|
||||
---------------------
|
||||
|
||||
Why keep an AUTHORS or a ChangeLog file, when git already has all of the
|
||||
information you need. AUTHORS generation supports filtering/combining based
|
||||
on a standard .mailmap file.
|
||||
|
||||
Sphinx Autodoc
|
||||
--------------
|
||||
|
||||
Sphinx can produce auto documentation indexes based on signatures and
|
||||
docstrings of your project- but you have to give it index files to tell it
|
||||
to autodoc each module. That's kind of repetitive and boring. PBR will
|
||||
scan your project, find all of your modules, and generate all of the stub
|
||||
files for you.
|
||||
|
||||
Sphinx documentation setups are altered to generate man pages by default. They
|
||||
also have several pieces of information that are known to setup.py injected
|
||||
into the sphinx config.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
You may not have noticed, but there are differences in how pip
|
||||
requirements.txt files work and how distutils wants to be told about
|
||||
requirements. The pip way is nicer, because it sure does make it easier to
|
||||
popuplate a virtualenv for testing, or to just install everything you need.
|
||||
Duplicating the information, though, is super lame. So PBR will let you
|
||||
keep requirements.txt format files around describing the requirements for
|
||||
your project, will parse them and split them up approprirately, and inject
|
||||
them into the install_requires and/or tests_require and/or dependency_links
|
||||
arguments to setup. Voila!
|
||||
|
||||
long_description
|
||||
----------------
|
||||
|
||||
There is no need to maintain two long descriptions- and your README file is
|
||||
probably a good long_description. So we'll just inject the contents of your
|
||||
README.rst, README.txt or README file into your empty long_description. Yay
|
||||
for you.
|
||||
|
||||
Usage
|
||||
=====
|
||||
pbr requires a distribution to use distribute. Your distribution
|
||||
must include a distutils2-like setup.cfg file, and a minimal setup.py script.
|
||||
|
||||
A simple sample can be found in pbr s own setup.cfg
|
||||
(it uses its own machinery to install itself)::
|
||||
|
||||
[metadata]
|
||||
name = pbr
|
||||
author = OpenStack Foundation
|
||||
author-email = openstack-dev@lists.openstack.org
|
||||
summary = OpenStack's setup automation in a reuable form
|
||||
description-file = README
|
||||
license = Apache-2
|
||||
classifier =
|
||||
Development Status :: 4 - Beta
|
||||
Environment :: Console
|
||||
Environment :: OpenStack
|
||||
Intended Audience :: Developers
|
||||
Intended Audience :: Information Technology
|
||||
License :: OSI Approved :: Apache Software License
|
||||
Operating System :: OS Independent
|
||||
Programming Language :: Python
|
||||
keywords =
|
||||
setup
|
||||
distutils
|
||||
[files]
|
||||
packages =
|
||||
pbr
|
||||
data_files =
|
||||
etc/init =
|
||||
pbr.packaging.conf
|
||||
pbr.version.conf
|
||||
[entry_points]
|
||||
console_scripts =
|
||||
pbr = pbr.cmd:main
|
||||
pbr.config.drivers =
|
||||
plain = pbr.cfg.driver:Plain
|
||||
|
||||
The minimal setup.py should look something like this::
|
||||
|
||||
#!/usr/bin/env python
|
||||
|
||||
from setuptools import setup
|
||||
|
||||
setup(
|
||||
setup_requires=['pbr'],
|
||||
pbr=True,
|
||||
)
|
||||
|
||||
Note that it's important to specify `pbr=True` or else the pbr functionality
|
||||
will not be enabled.
|
||||
|
||||
It should also work fine if additional arguments are passed to `setup()`,
|
||||
but it should be noted that they will be clobbered by any options in the
|
||||
setup.cfg file.
|
||||
|
||||
files
|
||||
-----
|
||||
|
||||
The format of the files section is worth explaining. There are three
|
||||
fundamental keys one is likely to care about, `packages`,
|
||||
`namespace_packages`, and `data_files`.
|
||||
|
||||
`packages` is a list of top-level packages that should be installed. The
|
||||
behavior of packages is similar to `setuptools.find_packages` in that it
|
||||
recurses the python package heirarchy below the given top level and installs
|
||||
all of it. If `packages` is not specified, it defaults to the name given
|
||||
in the `[metadata]` section.
|
||||
|
||||
`namespace_packages` is the same, but is a list of packages that provide
|
||||
namespace packages.
|
||||
|
||||
`data_files` lists files to be installed. The format is an indented block
|
||||
that contains key value pairs which specify target directory and source
|
||||
file to install there. More than one source file for a directory may be
|
||||
indicated with a further indented list. Source files are stripped of leading
|
||||
directories, so::
|
||||
|
||||
[files]
|
||||
data_files =
|
||||
etc/neutron =
|
||||
etc/api-paste.ini
|
||||
etc/dhcp-agent.ini
|
||||
etc/init.d = neutron.init
|
||||
|
||||
Will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
|
||||
both of which pbr will expect to find in the `etc` directory in the root of
|
||||
the source tree. Additionally, `neutron.init` from that dir will be installed
|
||||
in `/etc/init.d`.
|
||||
|
||||
entry_points
|
||||
------------
|
||||
|
||||
The general syntax of specifying entry points is a top level name indicating
|
||||
the entry point group name, followed by one or more key value pairs naming
|
||||
the entry point to be installed. For instance::
|
||||
|
||||
[entry_points]
|
||||
console_scripts =
|
||||
pbr = pbr.cmd:main
|
||||
pbr.config.drivers =
|
||||
plain = pbr.cfg.driver:Plain
|
||||
fancy = pbr.cfg.driver:Fancy
|
||||
|
||||
Will cause a console script called `pbr` to be installed that executes the
|
||||
`main` function found in `pbr.cmd`. Additionally, two entry points will be
|
||||
installed for `pbr.config.drivers`, one called `plain` which maps to the
|
||||
`Plain` class in `pbr.cfg.driver` and one called `fancy` which maps to the
|
||||
`Fancy` class in `pbr.cfg.driver`.
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
Loading…
Reference in New Issue