ltd-mason 0.2.0rc0

LSST the Docs build tool

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.

Installation

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 https://github.com/lsst-sqre/ltd-mason.git
pip install -r requirements.txt
python setup.py develop

See Testing for information on running unit tests.

Usage

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

LTD_MASON_AWS_ID

AWS access key ID.

LTD_MASON_AWS_SECRET

AWS secret access key.

LTD_MASON_AWS_PROFILE

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

LTD_KEEPER_URL

URL of LTD Keeper instance.

LTD_KEEPER_USER

Username for LTD Keeper instance.

LTD_KEEPER_PASSWORD

Password for LTD Keeper instance.

Testing

Unit and integration tests are available.

Unit tests

Developers can run unit tests via pytest:

py.test  --flake8 --cov=ltdmason

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:

LTD_MASON_TEST_AWS_ID

AWS access key ID

LTD_MASON_TEST_AWS_SECRET

AWS secret access key

LTD_MASON_TEST_BUCKET

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 https://pypi.python.org/pypi/ltd-mason/. Follow this procedure to create a new release:

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

2. Test the metadata:

   python setup.py check --metadata --restructuredtext --strict

3. Build the distributions:

   rm -R dist
   python setup.py sdist bdist_wheel

4. Upload the distributions with twine:

   twine upload dist/*

---

Copyright 2016 AURA/LSST.

License: MIT.