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

Installing for development/testing

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


pip install -r requirements.txt
python develop

See :ref:`Testing` for information on testing.


Mason is intended to be used as a command line app, ``ltd-mason``.
A YAML-encoded manifest file tells ``ltd-mason`` what documentation to built, and where to find individual LSST Stack packages built by lsstsw_.
The manifest's schema is described in `SQR-006`_, and examples are also available here in the :file:`tests/` and :file:`integration_tests/` directories.

Typical usage is::

ltd-mason --manifest manifest.yaml

Run ``ltd-mason --help`` for more information.


Unit and integration tests are available.

Unit tests

Developers can run unit tests via `pytest <>`_::


To run the full set of tests, the :envvar:`STACK_AFW` environment variable should be set to the path of the installed ``afw`` package in the ``lsstsw/stack`` directory.
Some tests will be skipped if :envvar:`STACK_AFW` is not set.

Integration tests

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


Copyright 2016 AURA/LSST.

License: MIT.

.. _SQR-006:
.. _lsstsw:

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.tar.gz (14.5 kB view hashes)

Uploaded Source

Built Distribution

ltd_mason-0.1.0-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