Development guide

This page provides procedures and guidelines for developing and contributing to technote.

Scope of contributions

technote is an open source package, meaning that you can contribute to technote itself, or fork technote for your own purposes.

Since technote is intended for internal use by Rubin Observatory, community contributions can only be accepted if they align with Rubin Observatory’s aims. For that reason, it’s a good idea to propose changes with a new GitHub issue before investing time in making a pull request.

technote is developed by the Rubin Observatory SQuaRE team.

Setting up a local development environment

Technote is a Python package, with Node.js involved for bundling web assets.

Python set up

To develop technote, create a virtual environment with your method of choice (like virtualenvwrapper) and then clone or fork, and install:

git clone https://github.com/lsst-sqre/technote.git
cd technote
make init

This init step does three things:

  1. Installs technote in an editable mode with its “dev” extra that includes test and documentation dependencies.

  2. Installs pre-commit and tox.

  3. Installs the pre-commit hooks.

Node.js set up

The Node.js version used by this project is intended to be built with a Node.js version that’s encoded in the .nvmrc file. To adopt this node version, we recommend installing and using the node version manager.

Then you can use the preferred node version by running nvm from the project root:

nvm use

Install the JavaScript packages:

npm install

Compile the dependencies:

npm run build

Pre-commit hooks

The pre-commit hooks, which are automatically installed by running the make init command on set up, ensure that files are valid and properly formatted. Some pre-commit hooks automatically reformat code:

isort

Automatically sorts imports in Python modules.

black

Automatically formats Python code.

blacken-docs

Automatically formats Python code in reStructuredText documentation and docstrings.

prettier

Formats JavaScript, CSS, and YAML.

When these hooks fail, your Git commit will be aborted. To proceed, stage the new modifications and proceed with your Git commit.

Running tests

To test the library, run tox, which tests the library the same way that the CI workflow does:

tox

To see a listing of test environments, run:

tox -av

To run a specific test or list of tests, you can add test file names (and any other pytest options) after -- when executing the py tox environment.

Building the demo technote

The demo technote, located in the demo directory of the repository, is used for getting feedback on how technotes build and look.

To build the demo site, use tox:

tox -e demo

The output technote site is located at ./demo/_built/html/index.html.

Compiling CSS and JS

The editable JS and CSS sources are located in the assets directory. Webpack compiles these assets into the /src/technote/theme/static directory, which is included in the Python package (but excluded from the Git repository).

To run webpack:

npm run build

Building documentation

Documentation is built with Sphinx, sourced from the docs directory:

tox -e docs

The built documentation is located in the docs/_build/html directory.

Updating the change log

Each pull request should update the change log (CHANGELOG.md). Add a description of new features and fixes as list items under a section at the top of the change log called “Unreleased:”

## Unreleased

- Description of the feature or fix.

If the next version is known (because Technotes’s main branch is being prepared for a new major or minor version), the section may contain that version information:

## X.Y.0 (unreleased)

- Description of the feature or fix.

If the exact version and release date is known (because a release is being prepared), the section header is formatted as:

## X.Y.0 (YYYY-MM-DD)

- Description of the feature or fix.

Style guide

Code

  • The code style follows PEP 8, though in practice lean on Black and isort to format the code for you.

  • Use PEP 484 type annotations. The tox -e typing test environment, which runs mypy, ensures that the project’s types are consistent.

  • Write tests for Pytest.

Documentation