Lowdown¶

Welcome to the Lowdown documentation. Lowdown is an extension for Sphinx that helps create beautiful, easy to read release notes for your project.

Installing¶

Installation is simple with pip:

pip install lowdown

Building from source¶

You can also build manually from the source for more control. First obtain a copy of the source by either downloading the zipball or cloning the public repository:

git clone git@bitbucket.org:ftrack/lowdown.git

Then you can build and install the package into your current Python site-packages folder:

python setup.py install

Alternatively, just build locally and manage yourself:

python setup.py build

Building documentation from source¶

To build the documentation from source:

python setup.py build_sphinx

Then view in your browser:

file:///path/to/lowdown/build/doc/html/index.html

Dependencies¶

Python >= 2.7, < 4
docutils >= 0.12, < 1’,
arrow >= 0.4.4, < 1’

Additional For building¶

Sphinx >= 1.8.5, < 4
sphinx_rtd_theme >= 0.1.6, < 1

Using¶

Once you have Lowdown installed, add it as an extension to your Sphinx configuration file:

# conf.py
extensions = [
    'lowdown'
]

Now add relevant release and change directives to an included source file, such as release.rst to detail each release:

.. release:: 0.1.0
    :date: 2015-01-01

    .. change:: new
        :tags: interface

        Added a fantastic new feature to the interface that you will all
        love.

    .. change:: fixed
        :changeset: c0381d8
        :tags: api, documentation

        Fixed an embarrisng issue in the API and updated documentation to
        be clearer as well.

    .. change:: changed
        :tags: interface

        That shiny button is now red!
        `Read more <http://en.wikipedia.org/wiki/Parkinson%27s_law_of_triviality>`_

Once built, it will look like:

Configuring¶

In the configuration file you can also specify Lowdown specific options to control the output:

lowdown_date_format¶: The format string to use with arrow.get when rendering the release date. Defaults to D MMMM YYYY.

lowdown_release_link¶: Control how release links are generated. Can be either a format string that has {value} in it where the release string should be, or a callable that accepts the release string and returns a full URI string. If not specified, release titles will be plain text and not links.

lowdown_changeset_link¶

Control how changeset links are generated. Can be either a format string that has {value} in it where the changeset string should be, or a callable that accepts the changeset string and returns a full URI string.

If not specified, changeset references will be plain text and not links.

Styling¶

By default, a lowdown.css stylesheet is added with some basic styling. Take a look to see which classes you can use in a custom stylesheet to further control styling.

API Reference¶

Releases¶

0.2.1 ¶

21 April 2021

change

Limit docutils to < 0.17 to avoid breaking with sphinx_rtd_theme.

0.2.0 ¶

10 June 2020

new

Provide support for python3.

0.1.3 ¶

12 February 2020

fixed

Copy stylesheet breaks on python3.

0.1.2 ¶

28 April 2017

fixed

Lists are not properly when included in a change directive.

0.1.1 ¶

30 May 2015

change

documentationUpdate documentation to reflect that package is now installable from PyPi.

0.1.0 ¶

6 January 2015

new

Initial release.

Includes support for specifying releases with specific changes listed. Each change supports tags as well as a main category and changeset link.

Indices and tables¶