Metadata-Version: 2.1
Name: added-value
Version: 0.8
Summary: Sphinx "added-value" extension
Home-page: https://github.com/sixty-north/added-value
Author: Robert Smallshire
Author-email: rob@sixty-north.com
License: BSD
Download-URL: https://pypi.python.org/pypi/added-value
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires: sphinx
Provides-Extra: test
Provides-Extra: docs
Requires-Dist: sphinx
Provides-Extra: docs
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: sphinx-testing; extra == 'test'

===========
Added Value
===========

A Sphinx extension for embedded representations of Python object values into documentation.

Added-value allows the *values* of Python objects to be incorporated into documentation.
This is achieved by adding new roles and directives which refer to Python objects in the
code being documented, much in the same way as the standard autodoc and autosummary
extensions work.

Roles
=====

The ``:repr:`` role inserts the *repr* representation of a Python object inline. For
example, given a Python module called ``values`` containing an global ``int`` called
``the_answer``, you can write:

::

  The answer to life, the Universe and everything is :repr:`values.the_answer`.


The ``:str:`` role inserts the *str* representation of a Python object inline. For
example, given a Python module called ``values`` containing an global ``int`` called
``the_answer``, you can write:

::

  The answer to life, the Universe and everything is :str:`values.the_answer`.


The ``:format:`` role inserts the *format* representation of a Python object inline. For
example, given the Python Standard Library ``math`` module containing the ``float``
called ``the_answer``, you can write:

::

  The value of pi to three decimal places is :format:`math.pi, .3f`.

The optional value after the comma is a format string as used by the built-in format
function and documented in the
`Format Specification Mini-Language <https://docs.python.org/3/library/string.html#format-specification-mini-language>`_


Directives
==========

The ``.. items-table::`` directive allows a tabular representation of a Python object to be included
in documentation.

For example, given a module called ``values`` which contains a list of lists called ``month_lengths``,
where each inner list contains a month name and the number of days in that month, a table can be
displayed like this:

::

  .. items-table:: values.month_lengths
     :header: Month, Length
     :stub-columns: 1

This adds a one-row header, and highlights the first 'stub' column (the month names).



