| 1 |
======= |
| 2 |
Usage |
| 3 |
======= |
| 4 |
|
| 5 |
*pbr* is a *setuptools* plugin and so to use it you must use *setuptools* and |
| 6 |
call ``setuptools.setup()``. While the normal *setuptools* facilities are |
| 7 |
available, *pbr* makes it possible to express them through static data files. |
| 8 |
|
| 9 |
.. _setup_py: |
| 10 |
|
| 11 |
``setup.py`` |
| 12 |
------------ |
| 13 |
|
| 14 |
*pbr* only requires a minimal ``setup.py`` file compared to a standard |
| 15 |
*setuptools* project. This is because most configuration is located in static |
| 16 |
configuration files. This recommended minimal ``setup.py`` file should look |
| 17 |
something like this: |
| 18 |
|
| 19 |
.. code-block:: python |
| 20 |
|
| 21 |
#!/usr/bin/env python |
| 22 |
|
| 23 |
from setuptools import setup |
| 24 |
|
| 25 |
setup( |
| 26 |
setup_requires=['pbr'], |
| 27 |
pbr=True, |
| 28 |
) |
| 29 |
|
| 30 |
.. note:: |
| 31 |
|
| 32 |
It is necessary to specify ``pbr=True`` to enabled *pbr* functionality. |
| 33 |
|
| 34 |
.. note:: |
| 35 |
|
| 36 |
While one can pass any arguments supported by setuptools to ``setup()``, |
| 37 |
any conflicting arguments supplied in ``pyproject.toml`` or ``setup.cfg`` |
| 38 |
will take precedence. |
| 39 |
|
| 40 |
Once configured, you can place your configuration into either |
| 41 |
``pyproject.toml`` or ``setup.cfg``. |
| 42 |
|
| 43 |
``pyproject.toml`` |
| 44 |
------------------ |
| 45 |
|
| 46 |
*If your project only supports Python 3.7 or newer*, PBR can be configured as a |
| 47 |
PEP517 build-system in ``pyproject.toml``. The main benefits are that you can |
| 48 |
control the versions of PBR and setuptools that are used avoiding easy_install |
| 49 |
invocation. Your ``[build-system]`` block in ``pyproject.toml`` will need to |
| 50 |
look like this: |
| 51 |
|
| 52 |
.. code-block:: toml |
| 53 |
|
| 54 |
[build-system] |
| 55 |
requires = ["pbr>=6.1.1"] |
| 56 |
build-backend = "pbr.build" |
| 57 |
|
| 58 |
Eventually PBR may grow its own direct support for PEP517 build hooks, but |
| 59 |
until then it will continue to need setuptools with a minimal ``setup.py`` and |
| 60 |
``setup.cfg`` as follows. First, ``setup.py``: |
| 61 |
|
| 62 |
.. code-block:: python |
| 63 |
|
| 64 |
import setuptools |
| 65 |
setuptools.setup(pbr=True) |
| 66 |
|
| 67 |
Then ``setup.cfg``: |
| 68 |
|
| 69 |
.. code-block:: ini |
| 70 |
|
| 71 |
[metadata] |
| 72 |
name = my_project |
| 73 |
|
| 74 |
Almost all other metadata can be placed into ``pyproject.toml``. A simple example: |
| 75 |
|
| 76 |
.. code-block:: toml |
| 77 |
|
| 78 |
[project] |
| 79 |
name = "my_project" |
| 80 |
description = "A brief one-line descriptive title of my project" |
| 81 |
authors = [ |
| 82 |
{name = "John Doe", email = "[email protected]"}, |
| 83 |
] |
| 84 |
requires-python = ">=3.10" |
| 85 |
classifiers = [ |
| 86 |
"Development Status :: 5 - Production/Stable", |
| 87 |
"Environment :: Console", |
| 88 |
"Intended Audience :: Developers", |
| 89 |
"Intended Audience :: Information Technology", |
| 90 |
"License :: OSI Approved :: Apache Software License", |
| 91 |
"Operating System :: OS Independent", |
| 92 |
"Programming Language :: Python", |
| 93 |
"Programming Language :: Python :: 3", |
| 94 |
"Programming Language :: Python :: 3.10", |
| 95 |
"Programming Language :: Python :: 3.11", |
| 96 |
"Programming Language :: Python :: 3.12", |
| 97 |
"Programming Language :: Python :: 3.13", |
| 98 |
"Topic :: Utilities", |
| 99 |
] |
| 100 |
keywords = ["commandline", "utility"] |
| 101 |
readme = "README.rst" |
| 102 |
|
| 103 |
[project.scripts] |
| 104 |
my-project = "my_project.cmd:main" |
| 105 |
|
| 106 |
[project.urls] |
| 107 |
Homepage = "https://my-project.example.org/" |
| 108 |
"Bug Tracker" = "https://my-project.example.org/bugs/" |
| 109 |
Documentation = "https://my-project.example.org/docs/" |
| 110 |
"Release Notes" = "https://my-project.example.org/releasenotes/" |
| 111 |
"Source Code" = "https://my-project.example.org/code/" |
| 112 |
|
| 113 |
[tool.setuptools] |
| 114 |
packages = ["my_project"] |
| 115 |
|
| 116 |
.. _setup_cfg: |
| 117 |
|
| 118 |
``setup.cfg`` |
| 119 |
------------- |
| 120 |
|
| 121 |
The ``setup.cfg`` file is an INI-like file that can mostly replace the |
| 122 |
``setup.py`` file. It is similar to the ``setup.cfg`` file found in recent |
| 123 |
versions of `setuptools`__. As with setuptools itself, you need to retain a |
| 124 |
minimal ``setup.py`` as follows: |
| 125 |
|
| 126 |
.. code-block:: python |
| 127 |
|
| 128 |
import setuptools |
| 129 |
setuptools.setup(pbr=True) |
| 130 |
|
| 131 |
All other metadata can be placed in your ``setup.cfg``. A simple example: |
| 132 |
|
| 133 |
.. code-block:: ini |
| 134 |
|
| 135 |
[metadata] |
| 136 |
name = my_project |
| 137 |
description = A brief one-line descriptive title of my project |
| 138 |
author = John Doe |
| 139 |
author_email = [email protected] |
| 140 |
classifiers = |
| 141 |
Development Status :: 5 - Production/Stable |
| 142 |
Environment :: Console |
| 143 |
Intended Audience :: Developers |
| 144 |
Intended Audience :: Information Technology |
| 145 |
License :: OSI Approved :: Apache Software License |
| 146 |
Operating System :: OS Independent |
| 147 |
Programming Language :: Python |
| 148 |
Programming Language :: Python :: 3 |
| 149 |
Programming Language :: Python :: 3.10 |
| 150 |
Programming Language :: Python :: 3.11 |
| 151 |
Programming Language :: Python :: 3.12 |
| 152 |
Programming Language :: Python :: 3.13 |
| 153 |
Topic :: Utilities |
| 154 |
keywords = commandline utility |
| 155 |
long_description = file: README.rst |
| 156 |
long_description_content_type = text/x-rst; charset=UTF-8 |
| 157 |
project_urls = |
| 158 |
Homepage = https://my-project.example.org/ |
| 159 |
Bug Tracker = https://my-project.example.org/bugs/ |
| 160 |
Documentation = https://my-project.example.org/docs/ |
| 161 |
Release Notes = https://my-project.example.org/releasenotes/ |
| 162 |
Source Code = https://my-project.example.org/code/ |
| 163 |
|
| 164 |
[options] |
| 165 |
python_requires = >=3.10 |
| 166 |
packages = |
| 167 |
my_project |
| 168 |
|
| 169 |
[options.entry_points] |
| 170 |
console_scripts = |
| 171 |
my-project = my_project.cmd:main |
| 172 |
|
| 173 |
Recent versions of `setuptools`_ provide many of the same sections as *pbr*. |
| 174 |
*pbr*'s support for setup.cfg predates that of setuptools'. For this reason |
| 175 |
*pbr* supports sections and functionality that setuptools never adopted. |
| 176 |
These sections are: |
| 177 |
|
| 178 |
- ``files`` (deprecated) |
| 179 |
- ``entry_points`` (deprecated) |
| 180 |
- ``backwards_compat`` (deprecated) |
| 181 |
- ``pbr`` |
| 182 |
|
| 183 |
In addition, there are some modifications to other sections: |
| 184 |
|
| 185 |
- ``metadata`` |
| 186 |
|
| 187 |
For all other sections, you should refer to either the `setuptools`_ |
| 188 |
documentation or the documentation of the package that provides the section, |
| 189 |
such as the ``extract_messages`` section provided by Babel__. |
| 190 |
|
| 191 |
.. note:: |
| 192 |
|
| 193 |
Comments may be used in ``setup.cfg``, however all comments should start |
| 194 |
with a ``#`` and may be on a single line, or in line, with at least one |
| 195 |
white space character immediately preceding the ``#``. Semicolons are not a |
| 196 |
supported comment delimiter. For instance: |
| 197 |
|
| 198 |
.. code-block:: ini |
| 199 |
|
| 200 |
[section] |
| 201 |
# A comment at the start of a dedicated line |
| 202 |
key = |
| 203 |
value1 # An in line comment |
| 204 |
value2 |
| 205 |
# A comment on a dedicated line |
| 206 |
value3 |
| 207 |
|
| 208 |
.. note:: |
| 209 |
|
| 210 |
On Python 3 ``setup.cfg`` is explicitly read as UTF-8. On Python 2 the |
| 211 |
encoding is dependent on the terminal encoding. |
| 212 |
|
| 213 |
__ http://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files |
| 214 |
__ http://babel.pocoo.org/en/latest/setup.html |
| 215 |
|
| 216 |
``files`` |
| 217 |
~~~~~~~~~ |
| 218 |
|
| 219 |
The ``files`` section defines the install location of files in the package. |
| 220 |
|
| 221 |
.. deprecated:: 7.0.0 |
| 222 |
|
| 223 |
`setuptools v30.3.0`__ introduced built-in support for configuring the |
| 224 |
below information via the ``[options]`` section in ``setup.cfg``, while |
| 225 |
`setuptools v68.1.0`__ adds support for doing this via ``pyproject.toml`` |
| 226 |
using the ``[tool.setuptools]`` section. For example, given the following |
| 227 |
``setup.cfg`` configuration: |
| 228 |
|
| 229 |
.. code-block:: ini |
| 230 |
|
| 231 |
[files] |
| 232 |
packages = |
| 233 |
foo |
| 234 |
namespace_packages = |
| 235 |
fooext |
| 236 |
data_files = |
| 237 |
etc/foo = etc/foo/* |
| 238 |
etc/foo-api = |
| 239 |
etc/api-paste.ini |
| 240 |
etc/init.d = foo.init |
| 241 |
|
| 242 |
You can represent this in ``setup.cfg`` like so: |
| 243 |
|
| 244 |
.. code-block:: ini |
| 245 |
|
| 246 |
[options] |
| 247 |
packages = |
| 248 |
foo |
| 249 |
namespace_packages = |
| 250 |
fooext |
| 251 |
|
| 252 |
[options.data_files] |
| 253 |
etc/foo = etc/foo/* |
| 254 |
etc/foo-api = |
| 255 |
etc/api-paste.ini |
| 256 |
etc/init.d = foo.init |
| 257 |
|
| 258 |
Neither namespace packages nor non-package data files are supported in |
| 259 |
``pyproject.toml`` format so only ``[files] packages`` can be migrated in |
| 260 |
this example: |
| 261 |
|
| 262 |
.. code-block:: toml |
| 263 |
|
| 264 |
[tool.setuptools] |
| 265 |
packages = ["foo"] |
| 266 |
|
| 267 |
For more information, refer to the `Configuring setuptools using setup.cfg |
| 268 |
files`__, `Package Discovery and Namespace Packages`__ and `Data Files |
| 269 |
Support`__ documents in the setuptools docs. |
| 270 |
|
| 271 |
.. __: https://pypi.org/project/setuptools/30.3.0/ |
| 272 |
.. __: https://pypi.org/project/setuptools/68.1.0/ |
| 273 |
.. __: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html |
| 274 |
.. __: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html |
| 275 |
.. __: https://setuptools.pypa.io/en/latest/userguide/datafiles.html |
| 276 |
|
| 277 |
The ``files`` section uses three fundamental keys: ``packages``, |
| 278 |
``namespace_packages``, and ``data_files``. |
| 279 |
|
| 280 |
``packages`` |
| 281 |
A list of top-level packages that should be installed. The behavior of |
| 282 |
packages is similar to ``setuptools.find_packages`` in that it recurses the |
| 283 |
Python package hierarchy below the given top level and installs all of it. If |
| 284 |
``packages`` is not specified, it defaults to the value of the ``name`` field |
| 285 |
given in the ``[metadata]`` section. For example: |
| 286 |
|
| 287 |
.. code-block:: ini |
| 288 |
|
| 289 |
[files] |
| 290 |
packages = |
| 291 |
pbr |
| 292 |
|
| 293 |
``namespace_packages`` |
| 294 |
Similar to ``packages``, but is a list of packages that provide namespace |
| 295 |
packages. For example: |
| 296 |
|
| 297 |
.. code-block:: ini |
| 298 |
|
| 299 |
[files] |
| 300 |
namespace_packages = |
| 301 |
pbrext |
| 302 |
|
| 303 |
``data_files`` |
| 304 |
A list of files to be installed. The format is an indented block that |
| 305 |
contains key value pairs which specify target directory and source file to |
| 306 |
install there. More than one source file for a directory may be indicated |
| 307 |
with a further indented list. Source files are stripped of leading |
| 308 |
directories. Additionally, *pbr* supports a simple file globbing syntax for |
| 309 |
installing entire directory structures. For example: |
| 310 |
|
| 311 |
.. code-block:: ini |
| 312 |
|
| 313 |
[files] |
| 314 |
data_files = |
| 315 |
etc/pbr = etc/pbr/* |
| 316 |
etc/neutron = |
| 317 |
etc/api-paste.ini |
| 318 |
etc/dhcp-agent.ini |
| 319 |
etc/init.d = neutron.init |
| 320 |
|
| 321 |
This will result in ``/etc/neutron`` containing ``api-paste.ini`` and |
| 322 |
``dhcp-agent.ini``, both of which *pbr* will expect to find in the ``etc`` |
| 323 |
directory in the root of the source tree. Additionally, ``neutron.init`` from |
| 324 |
that directory will be installed in ``/etc/init.d``. All of the files and |
| 325 |
directories located under ``etc/pbr`` in the source tree will be installed |
| 326 |
into ``/etc/pbr``. |
| 327 |
|
| 328 |
Note that this behavior is relative to the effective root of the environment |
| 329 |
into which the packages are installed, so depending on available permissions |
| 330 |
this could be the actual system-wide ``/etc`` directory or just a top-level |
| 331 |
``etc`` subdirectory of a *virtualenv*. |
| 332 |
|
| 333 |
``entry_points`` |
| 334 |
~~~~~~~~~~~~~~~~ |
| 335 |
|
| 336 |
The ``entry_points`` section defines entry points for generated console scripts |
| 337 |
and Python libraries. |
| 338 |
|
| 339 |
.. deprecated:: 7.0.0 |
| 340 |
|
| 341 |
`setuptools v30.3.0`__ introduced built-in support for configuring the |
| 342 |
below information via the ``[options.entry_points]`` section in |
| 343 |
``setup.cfg``, while `setuptools v68.1.0`__ adds support for doing this via |
| 344 |
``pyproject.toml`` using the ``[project.scripts]`` section. For example, |
| 345 |
given the following ``setup.cfg`` configuration: |
| 346 |
|
| 347 |
.. code-block:: ini |
| 348 |
|
| 349 |
[entry_points] |
| 350 |
console_scripts = |
| 351 |
pbr = pbr.cmd:main |
| 352 |
pbr.config.drivers = |
| 353 |
plain = pbr.cfg.driver:Plain |
| 354 |
fancy = pbr.cfg.driver:Fancy |
| 355 |
|
| 356 |
You can represent this in ``setup.cfg`` like so: |
| 357 |
|
| 358 |
.. code-block:: ini |
| 359 |
|
| 360 |
[options.entry_points] |
| 361 |
console_scripts = |
| 362 |
pbr = pbr.cmd:main |
| 363 |
pbr.config.drivers = |
| 364 |
plain = pbr.cfg.driver:Plain |
| 365 |
fancy = pbr.cfg.driver:Fancy |
| 366 |
|
| 367 |
Or in ``pyproject.toml`` like so: |
| 368 |
|
| 369 |
.. code-block:: toml |
| 370 |
|
| 371 |
[project.scripts] |
| 372 |
pbr = "pbr.cmd:main" |
| 373 |
|
| 374 |
[project.entry-points."pbr.config.drivers"] |
| 375 |
plain = "pbr.cfg.driver:Plain" |
| 376 |
fancy = "pbr.cfg.driver:Fancy" |
| 377 |
|
| 378 |
For more information, refer to the `Entry Points`__ document in the |
| 379 |
setuptools docs. |
| 380 |
|
| 381 |
.. __: https://pypi.org/project/setuptools/30.3.0/ |
| 382 |
.. __: https://pypi.org/project/setuptools/68.1.0/ |
| 383 |
.. __: https://setuptools.pypa.io/en/latest/userguide/entry_point.html |
| 384 |
|
| 385 |
The general syntax of specifying entry points is a top level name indicating |
| 386 |
the entry point group name, followed by one or more key value pairs naming the |
| 387 |
entry point to be installed. For example: |
| 388 |
|
| 389 |
.. code-block:: ini |
| 390 |
|
| 391 |
[entry_points] |
| 392 |
console_scripts = |
| 393 |
pbr = pbr.cmd:main |
| 394 |
pbr.config.drivers = |
| 395 |
plain = pbr.cfg.driver:Plain |
| 396 |
fancy = pbr.cfg.driver:Fancy |
| 397 |
|
| 398 |
Will cause a console script called *pbr* to be installed that executes the |
| 399 |
``main`` function found in ``pbr.cmd``. Additionally, two entry points will be |
| 400 |
installed for ``pbr.config.drivers``, one called ``plain`` which maps to the |
| 401 |
``Plain`` class in ``pbr.cfg.driver`` and one called ``fancy`` which maps to |
| 402 |
the ``Fancy`` class in ``pbr.cfg.driver``. |
| 403 |
|
| 404 |
``backwards_compat`` |
| 405 |
~~~~~~~~~~~~~~~~~~~~~ |
| 406 |
|
| 407 |
.. todo:: Describe this section |
| 408 |
|
| 409 |
.. _pbr-setup-cfg: |
| 410 |
|
| 411 |
``pbr`` |
| 412 |
~~~~~~~ |
| 413 |
|
| 414 |
The ``pbr`` section controls *pbr*-specific options and behaviours. |
| 415 |
|
| 416 |
``skip_git_sdist`` |
| 417 |
If enabled, *pbr* will not generate a manifest file from *git* commits. If |
| 418 |
this is enabled, you may need to define your own `manifest template`__. |
| 419 |
|
| 420 |
This can also be configured using the ``SKIP_GIT_SDIST`` environment |
| 421 |
variable, as described :ref:`here <packaging-tarballs>`. |
| 422 |
|
| 423 |
__ https://packaging.python.org/tutorials/distributing-packages/#manifest-in |
| 424 |
|
| 425 |
``skip_changelog`` |
| 426 |
If enabled, *pbr* will not generated a ``ChangeLog`` file from *git* commits. |
| 427 |
|
| 428 |
This can also be configured using the ``SKIP_WRITE_GIT_CHANGELOG`` |
| 429 |
environment variable, as described :ref:`here <packaging-authors-changelog>` |
| 430 |
|
| 431 |
``skip_authors`` |
| 432 |
If enabled, *pbr* will not generate an ``AUTHORS`` file from *git* commits. |
| 433 |
|
| 434 |
This can also be configured using the ``SKIP_GENERATE_AUTHORS`` environment |
| 435 |
variable, as described :ref:`here <packaging-authors-changelog>` |
| 436 |
|
| 437 |
``skip_reno`` |
| 438 |
If enabled, *pbr* will not generate a ``RELEASENOTES.txt`` file if `reno`_ is |
| 439 |
present and configured. |
| 440 |
|
| 441 |
This can also be configured using the ``SKIP_GENERATE_RENO`` environment |
| 442 |
variable, as described :ref:`here <packaging-releasenotes>`. |
| 443 |
|
| 444 |
.. versionchanged:: 6.0 |
| 445 |
|
| 446 |
The ``autodoc_tree_index_modules``, ``autodoc_tree_excludes``, |
| 447 |
``autodoc_index_modules``, ``autodoc_exclude_modules`` and ``api_doc_dir`` |
| 448 |
settings are all removed. |
| 449 |
|
| 450 |
.. versionchanged:: 4.2 |
| 451 |
|
| 452 |
The ``autodoc_tree_index_modules``, ``autodoc_tree_excludes``, |
| 453 |
``autodoc_index_modules``, ``autodoc_exclude_modules`` and ``api_doc_dir`` |
| 454 |
settings are all deprecated. |
| 455 |
|
| 456 |
.. versionchanged:: 2.0 |
| 457 |
|
| 458 |
The ``pbr`` section used to take a ``warnerrors`` option that would enable |
| 459 |
the ``-W`` (Turn warnings into errors.) option when building Sphinx. This |
| 460 |
feature was broken in 1.10 and was removed in pbr 2.0 in favour of the |
| 461 |
``[build_sphinx] warning-is-error`` provided in Sphinx 1.5+. |
| 462 |
|
| 463 |
``metadata`` |
| 464 |
~~~~~~~~~~~~ |
| 465 |
|
| 466 |
.. todo:: Describe this section |
| 467 |
|
| 468 |
.. _build_sphinx-setup-cfg: |
| 469 |
|
| 470 |
``build_sphinx`` |
| 471 |
~~~~~~~~~~~~~~~~ |
| 472 |
|
| 473 |
.. versionchanged:: 3.0 |
| 474 |
|
| 475 |
The ``build_sphinx`` plugin used to default to building both HTML and man |
| 476 |
page output. This is no longer the case, and you should explicitly set |
| 477 |
``builders`` to ``html man`` if you wish to retain this behavior. |
| 478 |
|
| 479 |
.. deprecated:: 4.2 |
| 480 |
|
| 481 |
This feature has been superseded by the `sphinxcontrib-apidoc`_ (for |
| 482 |
generation of API documentation) and :ref:`pbr.sphinxext` (for configuration |
| 483 |
of versioning via package metadata) extensions. It has been removed in |
| 484 |
version 6.0. |
| 485 |
|
| 486 |
Requirements |
| 487 |
------------ |
| 488 |
|
| 489 |
Requirements files are used in place of the ``install_requires`` and |
| 490 |
``extras_require`` attributes. Requirement files should be given one of the |
| 491 |
below names. This order is also the order that the requirements are tried in: |
| 492 |
|
| 493 |
* ``requirements.txt`` |
| 494 |
* ``tools/pip-requires`` |
| 495 |
|
| 496 |
Only the first file found is used to install the list of packages it contains. |
| 497 |
|
| 498 |
.. versionchanged:: 5.0 |
| 499 |
|
| 500 |
Previously you could specify requirements for a given major version of |
| 501 |
Python using requirements files with a ``-pyN`` suffix. This was deprecated |
| 502 |
in 4.0 and removed in 5.0 in favour of environment markers. |
| 503 |
|
| 504 |
.. _extra-requirements: |
| 505 |
|
| 506 |
Extra requirements |
| 507 |
~~~~~~~~~~~~~~~~~~ |
| 508 |
|
| 509 |
Groups of optional dependencies, or `"extra" requirements`__, can be described |
| 510 |
in your ``setup.cfg``, rather than needing to be added to ``setup.py``. An |
| 511 |
example (which also demonstrates the use of environment markers) is shown |
| 512 |
below. |
| 513 |
|
| 514 |
__ https://www.python.org/dev/peps/pep-0426/#extras-optional-dependencies |
| 515 |
|
| 516 |
Environment markers |
| 517 |
~~~~~~~~~~~~~~~~~~~ |
| 518 |
|
| 519 |
Environment markers are `conditional dependencies`__ which can be added to the |
| 520 |
requirements (or to a group of extra requirements) automatically, depending on |
| 521 |
the environment the installer is running in. They can be added to requirements |
| 522 |
in the requirements file, or to extras defined in ``setup.cfg``, but the format |
| 523 |
is slightly different for each. |
| 524 |
|
| 525 |
For ``requirements.txt``:: |
| 526 |
|
| 527 |
argparse; python_version=='2.6' |
| 528 |
|
| 529 |
This will result in the package depending on ``argparse`` only if it's being |
| 530 |
installed into Python 2.6. |
| 531 |
|
| 532 |
For extras specified in ``setup.cfg``, add an ``extras`` section. For instance, |
| 533 |
to create two groups of extra requirements with additional constraints on the |
| 534 |
environment, you can use: |
| 535 |
|
| 536 |
.. code-block:: ini |
| 537 |
|
| 538 |
[extras] |
| 539 |
security = |
| 540 |
aleph |
| 541 |
bet:python_version=='3.2' |
| 542 |
gimel:python_version=='2.7' |
| 543 |
testing = |
| 544 |
quux:python_version=='2.7' |
| 545 |
|
| 546 |
__ https://www.python.org/dev/peps/pep-0426/#environment-markers |
| 547 |
|
| 548 |
|
| 549 |
Sphinx ``conf.py`` |
| 550 |
------------------ |
| 551 |
|
| 552 |
As described in :doc:`/user/features`, *pbr* provides a Sphinx extension to |
| 553 |
automatically configure the version numbers for your documentation using *pbr* |
| 554 |
metadata. |
| 555 |
|
| 556 |
To enable this extension, you must add it to the list of extensions in |
| 557 |
your ``conf.py`` file: |
| 558 |
|
| 559 |
.. code-block:: python |
| 560 |
|
| 561 |
extensions = [ |
| 562 |
'pbr.sphinxext', |
| 563 |
# ... other extensions |
| 564 |
] |
| 565 |
|
| 566 |
You should also unset/remove the ``version`` and ``release`` attributes from |
| 567 |
this file. |
| 568 |
|
| 569 |
.. _setuptools: http://www.sphinx-doc.org/en/stable/setuptools.html |
| 570 |
.. _sphinxcontrib-apidoc: https://pypi.org/project/sphinxcontrib-apidoc/ |
| 571 |
.. _reno: https://docs.openstack.org/reno/latest/ |