lsst-sphinx-bootstrap-theme
This is a prototype Sphinx theme for LSST Stack documentation, based on the Astropy Sphinx theme.
Getting started with development
Get the repo:
git clone https://github.com/lsst-sqre/lsst-sphinx-bootstrap-theme cd lsst-sphinx-bootstrap-theme
Install JavaScript dependencies:
npm install -g gulp-cli npm install
Compile the assets and continue watching for changes:
gulp
Codebase orientation
-
lsst_sphinx_bootstrap_theme/
is the theme's Python package-
static/
is for static assets deployed onto the site.app.css
is generated withgulp
, so don't edit it directly. -
layout.html
is the main Jinja2 template for the HTML. The other HTML files are blocks/partials.
-
-
scss/
contains Sass source files that get compiled intolsst_sphinx_bootstrap_theme/static/app.css
.
Gulp commands
This project uses Gulp to run its build pipelines. This section describes the gulp commands you can run.
gulp
Use this default command for development. It does the following:
- sass (compile Sass)
- Watches for changes and recompiles assets as necessary.
gulp scss
Compile Sass into CSS (app.css
).
We use the following features:
- Compile Sass.
- Add prefixes to CSS using Autoprefixer (via PostCSS).
- Clean and compress the CSS using gulp-clean-css.
You can run this task alone, but usually through gulp
(default task).
gulp pretty
Automatically format code. See Code style via Prettier.
Code style via Prettier
This project uses Prettier to make sure the Sass and JavaScript are formatted as you'd expect.
Like most projects, we use Prettier nearly as-is.
A couple minor exceptions are configured in .prettierrc.yaml
.
You can run Prettier two ways:
- Manually, by running gulp pretty.
- Automatically, by committing code.
This is configured as a pre-commit hook in
package.json
.
Note that Prettier's pre-commit hook and chunked git commits don't mix. You'll want to manually run Prettier before committing a subset of the changed lines in your files.
Release process
-
Update the change log (
CHANGELOG.rst
), commit, and marge work tomaster
. -
Tag the release using a PEP 440-compatible version string:
git tag -s X.Y.Z -m "X.Y.Z"
Push the tag:
git tags --push
The Travis CI pipeline will create and upload the release to PyPI.