Added Value

Added Value is a tool which makes it easy to embed values extracted from Python modules in Sphinx documentation. This allows important constants, collections and tables to have a single source of truth in the software, so that documentation always faithfully represents the underlying values used by the software. Uses of Added Value are not specific to documenting source code, although it can help in that task in conjunction with Sphinx’ tools for such at the roles and directives in the Python, and other language domains.

Installation

Install using pip:

pip install added-value

Some Quick Examples

Using added value we can extract the value of pi from the Python Standard Library math module, and embed it in a sentence, using Added Values’s format role:

The ratio of the circumference to the diameter of a circle is :format:`math.pi, .3f` to three
decimal places.

Which gives:

The ratio of the circumference to the diameter of a circle is 3.142 to three decimal places.

Added value is powerful, and allows lists, dictionaries, and even complex data structures such as lists of lists of dictionaries to be rendered into text in various ways. Consider the following dictionary of dictionaries of dictionaries:

economic_data = {
    "United States": {
        "GDP %": {
            "latest": 3.0,
            "quarter": 3.5,
            "2018": 2.9,
        },
        "Consumer prices %": {
            "latest": 2.3,
            "2018": 2.5,
        },
        "Unemployment rate %": {
            "latest": 3.7,
        },
    },
    "China": {
        "GDP %": {
            "latest": 6.5,
            "quarter": 6.6,
            "2018": 6.6,
        },
        "Consumer prices %": {
            "latest": 2.5,
            "2018": 2.1,
        },
        "Unemployment rate %": {
            "latest": 3.8,
        },
    },
    "Japan": {
        "GDP %": {
            "latest": 1.3,
            "quarter": 3.0,
            "2018": 1.0,
        },
        "Consumer prices %": {
            "latest": 1.2,
            "2018": 0.9,
        },
        "Unemployment rate %": {
            "latest": 2.3,
        },
    },
    "Britain": {
        "GDP %": {
            "latest": 1.2,
            "quarter": 1.6,
            "2018": 1.3,
        },
        "Consumer prices %": {
            "latest": 2.4,
            "2018": 2.4,
        },
        "Unemployment rate %": {
            "latest": 4.0,
        },
    },
}

usa_economic_data = {country: data for country, data in economic_data.items() if country == "United States"}

Using Added Value’s items-table directive, we can embed this into the documentation as a table:

.. items-table:: economy.economic_data
   :title: **Economic Data**
   :v-level-indexes: 0
   :h-level-indexes: 1, 2
   :header-rows: 2
   :stub-columns: 1

which when rendered, looks like this:

Economic Data

GDP %

Consumer prices %

Unemployment rate %

latest

quarter

2018

latest

2018

latest

United States

3.0

3.5

2.9

2.3

2.5

3.7

China

6.5

6.6

6.6

2.5

2.1

3.8

Japan

1.3

3.0

1.0

1.2

0.9

2.3

Britain

1.2

1.6

1.3

2.4

2.4

4.0

Reference Documentation

Added Value knows how to create scalar values, lists, and tables from Python objects. Check out the reference documentation for more details:

Indices and tables