|Author||Association of Universities for Research in Astronomy, Inc.|
HTML landing page generator for LSST PDF documentation deployed from Git to LSST the Docs.
Lander works with Python 3.5 or above. You can install it from PyPI:
pip install lander
Run lander -h for command line help.
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
With the --lsstdoc <tex path> argument, Lander will attempt to scrape metadata from the source of a lsstdoc-class LaTeX file, including:
Note that Lander does not convert LaTeX commands to HTML. In these cases, the metadata needs to be added explicitly. We plan to address this in future releases.
See https://lsst-texmf.lsst.io for information about the lsstdoc class.
If you’re running on Travis CI, set the --env=travis to get metadata from Travis’s environment variables:
Lander tries to get as much metadata from the environment as possible, but sometimes this isn’t possible or usable. For example, Lander can’t (yet) convert LaTeX expressions into HTML. In this case you can explicitly set metadata with these flags (see lander -h for more information):
--authors should be a JSON-formatted array, even for a single author. For example:
--authors "[\"First Author\", \"Second Author\"]"
To include ancillary files with the main PDF document, provide their file paths with the --extra-downloads path. These extra files are listed in the Downloads section of the landing page. The main PDF is always included first in this list.
--extra-downloads should be a JSON-formatted array, even for a single item. For example:
Lander works well with LSST the Docs. Lander can upload pages directly to LSST the Docs for you with these configurations:
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.
You need both Python 3.5+ and node.js to develop Lander.
Clone and install dependencies (use a Python virtual environment of your choice):
git clone https://github.com/lsst-sqre/lander cd lander npm install pip install -r requirements.txt python setup.py develop
We use pytest:
The default gulp workflow create website assets and generates a test website:
gulp assets --env=deploy
This is how assets are built on CI for releases of Lander.
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
This project is open sourced under the MIT license. See LICENSE for details.