Skip to main content

LSST the Docs build tool

Project description

LSST the Docs: Mason

Mason is the build tool for LSST software documentation that runs in the Jenkins build environment. It is a part of the LSST the Docs (LTD) service for continuous documentation deployment. You can learn more about LTD in our SQR-006 technote.


Mason is intended to work with either Python 2.7, 3.4, or 3.5.

We recommend that you install Mason inside a virtual environment (such as virtualenv / virtualenvwrapper on Python 2.7/3 or the built-in pyenv for Python 3).

If the Sphinx project being built uses Python introspection to build an API reference with autodoc or numpydoc, then the Python package being documented must be installed in the same virtual environment as Mason.

Install for production

Mason is available on PyPI:

pip install ltd-mason

Next, see the Usage section.

Install for development/testing

Once the environment is ready, install Mason from this Git repository via:

git clone
pip install -r requirements.txt
python develop

See Testing for information on running unit tests.


Mason is intended to be used as a command line app, ltd-mason. typical usage is:

ltd-mason --manifest manifest.yaml

See ltd-mason -h for additional options.

YAML Manifest

A YAML-encoded manifest file tells ltd-mason what documentation to build, and where to find individual packages for multi-package LSST Stack-type build. The manifest’s schema is described in SQR-006, and examples are also available here in the tests/ and integration_tests/ directories. Formally the manifest schema is defined in manifest_schema.yaml.

Enviroment Variables and AWS credentials

LTD Mason is configured through environment variables.

Credentials for AWS S3

AWS access key ID.


AWS secret access key.


This variable can be set as an alternative LTD_MASON_AWS_ID and LTD_MASON_AWS_SECRET. LTD_MASON_AWS_PROFILE is the name of a profile in ~/.aws/credentials that contains your secret key and ID. See the boto3 configuration guide for more information.

If None of these variables are configured, LTD Mason will attempt to use the default AWS credential setup in your environment.

Note that the AWS credentials specified here must have permission to read and write into the S3 buckets managed by the LTD Keeper server.

Credentials for LTD Keeper

URL of LTD Keeper instance.


Username for LTD Keeper instance.


Password for LTD Keeper instance.


Unit and integration tests are available.

Unit tests

Developers can run unit tests via pytest:


To run a full suite of AWS S3 integration tests, you’ll need AWS credentials and an S3 bucket to test in. Configure the tests to use these by setting the following environment variables:


AWS access key ID


AWS secret access key


Name of an S3 bucket that already exists and can be used for testing.

Integration tests

We have separate integration tests to exercise code that interacts with AWS S3 and ltd-keeper. See integration_tests/README.rst for instructions on how to run these integration tests.

Release Procedures

LTD Mason is distributed with PyPI at Follow this procedure to create a new release:

  1. Ensure the version in is correct. Use x.y.z.devN for development versions.

  2. Test the metadata:

    python check --metadata --restructuredtext --strict
  3. Build the distributions:

    rm -R dist
    python sdist bdist_wheel
  4. Upload the distributions with twine:

    twine upload dist/*

Copyright 2016 AURA/LSST.

License: MIT.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ltd-mason-0.1.0.dev0.tar.gz (14.5 kB view hashes)

Uploaded Source

Built Distribution

ltd_mason-0.1.0.dev0-py3-none-any.whl (16.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page