HTML landing page generator for LSST PDF documentation deployed from Git to LSST the Docs.
Project description
HTML landing page generator for LSST PDF documentation deployed from Git to LSST the Docs.
Installation
Lander works with Python 3.5 or above. You can install it from PyPI:
pip install lander
Run lander -h for command line help.
Usage
Basic usage
To create a landing page website, run lander with the local PDF file’s path:
lander --pdf <path>
The built PDF landing page site is available, by default, from the _build directory. View the site in a browser by running a Python web server:
cd _build && python -m http.server 8000 --bind 127.0.0.1
Get metadata from an lsstdoc document
With the --lsstdoc <tex path> argument, Lander will attempt to scrape metadata from the source of a lsstdoc-class LaTeX file, including:
abstract
authors
document handle
title
See https://lsst-texmf.lsst.io for information about the lsstdoc class.
Get metadata from the Travis environment
If you’re running on Travis CI, set the --env=travis to get metadata from Travis’s environment variables:
$TRAVIS_COMMIT
$TRAVIS_BRANCH
$TRAVIS_TAG
$TRAVIS_REPO_SLUG
$TRAVIS_JOB_NUMBER
Overriding metadata
Lander tries to get as much metadata from the environment as possible (including from the Git repository and the LaTeX document itself), but sometimes this isn’t possible. In this case you can explicitly set metadata with these flags (see lander -h for more information):
--abstract
--authors (see note)
--title
--handle (such as LDM-151)
--repo-url (such as https://github.com/lsst/ldm-151)
--repo-branch (such as master)
--date (such as 2017-05-22)
--docushare-url (prefer the multi-version form, https://ls.st/ldm-151*)
--authors should be a JSON-formatted array, even for a single author. For example:
--authors "[\"First Author\", \"Second Author\"]"
Distributing extra files from the landing page
To include ancillary files with the main PDF document, provide their file paths with the --extra-downloads argument. These extra files are listed in the Downloads section of the landing page. The main PDF is always included first in this list.
For example:
--extra-downloads demo.ipynb
Uploading to LSST the Docs
Lander works well with LSST the Docs. Lander can upload pages directly to LSST the Docs for you with these configurations:
--upload — provide this flag to indicate a build should be uploaded.
--ltd-product — Name of the product on LSST the Docs.
--keeper-url or $LTD_KEEPER_URL.
--keeper-user or $LTD_KEEPER_USER.
--keeper-password or $LTD_KEEPER_PASSWORD.
--aws-id or $LTD_AWS_ID.
--aws-secret or $LTD_AWS_SECRET.
Note: these are advanced configurations and are typically added to a CI configuration automatically or by a Documentation Engineer. Reach out to #dm-docs on Slack for help.
Development workflow
You need both Python 3.5+ and node.js to develop Lander.
Initial set up
Clone and install dependencies (use a Python virtual environment of your choice):
git clone https://github.com/lsst-sqre/lander cd lander npm install gulp assets pip install -e ".[dev]"
Run Python tests and linting
We use pytest for unit testing and style checks:
make pytest
You can also run end-to-end trials of landing page builds:
make test
These integration tests clone real LSST documents, compiles them with Docker, and builds landing pages to simulate continuous delivery workflows in production. Look for sites in _tests.
Build a development site
The default gulp workflow creates website assets and generates a test website:
gulp
This gulp task runs a browsersync server and refreshes the page whenever CSS, JavaScript, or HTML assets change.
Only build assets
If you want to only build CSS, icon, and JavaScript assets, run this task:
gulp assets --env=deploy
This is how assets are built on CI for releases of Lander.
Developing CSS/Sass with squared
Lander uses squared for visual design. All Lander CSS should be committed to the squared repo so that LSST SQuaRE web projects share a common visual language.
To make it easier to write Sass in squared while developing landing pages in Lander, we recommend linking a clone of squared to Lander’s node_modules. Assuming you’re starting from the lander/ root directory:
git clone https://github.com/lsst-sqre/squared ../squared npm link ../squared
Some patterns:
If you’re working on a branch in squared, then update squared’s version in package.json to that branch. For example: "squared": "lsst-sqre/squared#tickets/DM-10503". This allows Travis to install the development version of squared when testing Lander. Remember to make a release of squared before releasing a new version of Lander, see below.
scss/app.scss in the lander repo imports Sass partials from squared and other packages (including inuitcss).
Release workflow
Update package.json with the released version of squared. Using tagged npm releases is preferred to GitHub branches to make builds of releases repeatable.
Create a signed tag: git tag -s 0.1.0 -m "v0.1.0". Use the PEP 440 schema.
Push the tag: git push --tags. This will automatically create a Lander release on PyPI.
Merge the development branch as necessary.
License
This project is open sourced under the MIT license. See LICENSE for details.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file lander-0.1.14a2.tar.gz.
File metadata
- Download URL: lander-0.1.14a2.tar.gz
- Upload date:
- Size: 2.7 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.14.2 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.6.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0d919083dd75f3a03f4d9245a683bcf2220e5e4a4a6f7679b487d83bbbbd0f0d |
|
| MD5 | e42c63fb6de690a29ec74d1d4f81d7a7 |
|
| BLAKE2b-256 | cd6a0bf8cbd1996c691171faff1aae52b6da18be95f5972c0d5b901d8e815f5a |
File details
Details for the file lander-0.1.14a2-py3-none-any.whl.
File metadata
- Download URL: lander-0.1.14a2-py3-none-any.whl
- Upload date:
- Size: 36.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.14.2 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.6.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | de70c33755ae1165572a60ac084f817f72c216cbd6a852507897536b39a1db68 |
|
| MD5 | 363be7b6d1f9e46a0deaa493892ae449 |
|
| BLAKE2b-256 | f5a48d0f00cb59b15034f83885e3edcc83a04a7a29b308fa7cfda403044a33e4 |
