Package: lander
LanderHTML landing page generator for LSST PDF documentation deployed from Git to LSST the Docs.InstallationLander works with Python 3.5 or above.
You can install it from PyPI:pip install landerRunlander-hfor command line help.UsageBasic usageTo create a landing page website, runlanderwith the local PDF file’s path:lander --pdf <path>The built PDF landing page site is available, by default, from the_builddirectory.
View the site in a browser by running a Python web server:cd _build && python -m http.server 8000 --bind 127.0.0.1Get metadata from an lsstdoc documentWith the--lsstdoc<tex path>argument, Lander will attempt to scrape metadata from the source of alsstdoc-class LaTeX file, including:abstractauthorsdocument handletitleSeehttps://lsst-texmf.lsst.iofor information about thelsstdocclass.Get metadata from the Travis environmentIf you’re running on Travis CI, set the--env=travisto get metadata from Travis’s environment variables:$TRAVIS_COMMIT$TRAVIS_BRANCH$TRAVIS_TAG$TRAVIS_REPO_SLUG$TRAVIS_JOB_NUMBEROverriding metadataLander 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 (seelander-hfor more information):--abstract--authors(see note)--title--handle(such asLDM-151)--repo-url(such ashttps://github.com/lsst/ldm-151)--repo-branch(such asmaster)--date(such as2017-05-22)--docushare-url(prefer the multi-version form,https://ls.st/ldm-151*)--authorsshould be a JSON-formatted array, even for a single author.
For example:--authors "[\"First Author\", \"Second Author\"]"Distributing extra files from the landing pageTo include ancillary files with the main PDF document, provide their file paths with the--extra-downloadargument.
These extra files are listed in theDownloadssection of the landing page.
The main PDF is always included first in this list.For example:--extra-download demo.ipynbUploading to LSST the DocsLander 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-urlor$LTD_KEEPER_URL.--keeper-useror$LTD_KEEPER_USER.--keeper-passwordor$LTD_KEEPER_PASSWORD.--aws-idor$LTD_AWS_ID.--aws-secretor$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-docson Slack for help.Development workflowYou need both Python 3.5+ andnode.jsto develop Lander.Initial set upClone and install dependencies (use a Python virtual environment of your choice):git clone https://github.com/lsst-sqre/lander
cd lander
npm install -g gulp-cli
npm install
gulp assets
pip install -e ".[dev]"Run Python tests and lintingWe use pytest for unit testing and style checks:make pytestYou can also run end-to-end trials of landing page builds:make testThese 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 siteThe defaultgulpworkflow creates website assets and generates a test website:gulpThis gulp task runs abrowsersyncserver and refreshes the page whenever CSS, JavaScript, or HTML assets change.Only build assetsIf you want to only build CSS, icon, and JavaScript assets, run this task:gulp assets --env=deployThis is how assets are built on CI for releases of Lander.Developing CSS/Sass with squaredLander usessquaredfor visual design.
All Lander CSS should be committed to thesquaredrepo so that LSST SQuaRE web projects share a common visual language.To make it easier to write Sass insquaredwhile developing landing pages in Lander, we recommend linking a clone ofsquaredto Lander’snode_modules.
Assuming you’re starting from thelander/root directory:git clone https://github.com/lsst-sqre/squared ../squared
npm link ../squaredSome patterns:If you’re working on a branch insquared, then update squared’s version inpackage.jsonto that branch.
For example:"squared":"lsst-sqre/squared#tickets/DM-10503".
This allows Travis to install the development version ofsquaredwhen testing Lander.
Remember to make a release ofsquaredbefore releasing a new version of Lander, see below.scss/app.scssin the lander repo imports Sass partials fromsquaredand other packages (includinginuitcss).Release workflowIfsquaredwas modified, create asquaredrelease first.Updatepackage.jsonwith the released version ofsquared.
Using tagged npm releases is preferred to GitHub branches to make builds of releases repeatable.Create a signed tag:git tag-s0.1.0-m"v0.1.0". Use thePEP 440schema.Push the tag:git push--tags. This will automatically create a Lander release on PyPI.Merge the development branch as necessary.LicenseThis project is open sourced under the MIT license.
SeeLICENSEfor details.Change Log1.0.6 (2023-07-04)Pinpydantic<2.0.0.Drop support for Python 3.7.1.0.1 (2021-05-11)Pin click<8 since Click 8.0.0 currently triggers the--versionmode, regardless of whether it was set on the command-line or not.1.0.0 (2021-01-06)This is the first release of Lander!
The version 1 release line is based on the 0.1 releases, and this line will continue to be maintained for existing users of Lander.A new version of Lander is under development, version 2.0, that will include a plugin interface for adding custom document parsers and website themes.0.1.16 (2019-07-04)Update Jinja to >=2.10.1 to address CVE-2019-10906.Update asset build pipeline to Gulp 4 and update all other npm dependencies at the same time.0.1.15 (2019-04-02)Update tolsst-projectmeta-kitto 0.3.5 for better author parsing.Updaterequeststo 2.20.0 (security).0.1.14 (2019-02-18)Lander will now cleanly abort when building on Travis CI, but the secure environment variables are not available.
This happens if the build is triggered by a fork.Switched to use$TRAVIS_BUILD_WEB_URLto get a URL to the build.
This is better than computing the build URL during the travis-ci.org to travis-ci.com transition.Updated test dependencies to pytest 4.2.1.Switched tosetuptools_scmfor version string management.0.1.13 (2018-11-26)Update to lsst-projectmeta-kit 0.3.3 for improved detection of\inputand\includecommands in TeX source.0.1.12 (2018-02-10)Update tolsst-projectmeta-kit0.3.1 for more reliablemetadata.jsonldgeneration (works around pandoc issues converting some documents to plain text).
There’s a new integration testmake dmtn070that demos this.Improve the testing strategy:
- Runmake pytestto run pytest with the correct arguments instead of using--add-optsin setup.cfg. This lets us runpytestdirectly with ad hoc arguments.
- Runmake testto run both pytest and the integration tests.0.1.11 (2018-02-07)Lander now creates and uploads ametadata.jsonlddocument alongside the landing page content (e.g.,index.html).
This content can be ingested by other tools into the LSST Projectmeta database.Switch from metasrc to lsst-projectmeta-kit 0.3.0.
It’s the same package, but the new and rebranded lsst-projectmeta-kit includes the ability to generate JSON-LD from anLsstLatexDocobject.0.1.10 (2017-12-11)Change known domain for DocuShare fromdocushare.lsstcorp.orgtodocushare.lsst.org.
This ensures thatls.stshort links can continue to be verified.Create default values forabstract_plainandtitle_plain.
This fixes cases where the abstract is not set in the underlying LaTeX document.0.1.9 (2017-11-20)Update metasrc to 0.2.2 to resolve issues with auto-downloading Pandoc in Travis CI (DM-12569).Update pytest to 3.2.5 and pytest-flake8 to 0.9.1 to fix incompatibilities in the floating indirect dependencies.0.1.8 (2017-10-09)Update metasrc to 0.2.1Use metasrc’sLsstLatexDoc.revision_datetimeto obtain the date of a document.
This method uses a combination of parsing the\dateLaTeX command, looking at content
Git commits, and falling back to ‘now’ to get an appropriate timestamp.0.1.7 (2017-09-28)Update metasrc to 0.2.0.
This provides Pandoc integration for improved HTML rendering of content extracted from LaTeX documents.Improve how loggers are configured (warning level for third-party loggers, and info/debug levels for first-party LSST SQuaRE code).0.1.6 (2017-09-07)Update metasrc to 0.1.4.
This update provides improved LaTeX command metadata extraction.
(DM-11821)Temporarily skip ls.st and DocuShare-related unit tests because ls.st links to DocuShare are broken due to the DocuShare upgrade.0.1.5 (2017-07-12)Pin to metasrc 0.1.3Via metasrc, Lander has improved LaTeX source processing, including handling of referenced source files (\inputand\include) and macros (\defand\newcommand).Improved treatment of draft status.
The heuristic is that a document is considered a draft if the branch is notmasterandlsstdraftis not present in a lsstdoc document’s options.0.1.4 (2017-07-06)Fix logic for determining it Lander is running in a Travis PR environment.Log the Lander version at startup.0.1.3 (2017-07-02)Fixed Travis deployment issue. Usedskip_cleanup: trueto.travis.ymlto prevent CSS and JS assets from bring cleaned up before creating a release.0.1.2 (2017-06-27)Detect if running from a Travis PR build (using theTRAVIS_PULL_REQUESTenvironment variable) and if so, abort the page build and upload.
This is to prevent duplicate uploads from both branch and PR-based Travis jobs.Pin inuitcss to 6.0.0-beta4 because of the removal of rem functions in beta5.0.1.1 (2017-06-17)Update tometasrc>=0.1.1,<0.2.Useremove_commentsandremove_trailing_whitespacefeature from metasrc.
This improves the accuracy of metadata extraction from tex source.
For example, comment characters won’t appear in extract abstract content.0.1.0 (2017-05-24)Initial version.Native PDF display viaPDFObject.Multi-level metadata model for populating the landing page.
Lander useshttps://github.com/lsst-sqre/metasrcto extract content from thetexsource (more work on this is needed).
Otherwise, it gets data from environment variables (including Travis CI variables).
Finally, metadata can be specified explicitly with command line arguments.Useshttps://github.com/lsst-sqre/squaredfor CSS, icons, and logos.
A Gulp and webpack workflow build these sources into deployable dependencies.
Gulp and webpack are only needed by developers and CI; the deployable artifacts are included in PyPI releases.Release workflow is fully automated in Travis.
Create a PEP 440 version tag, push it, and the release appears in PyPI.Includes an LSST the Docs upload client (viahttps://github.com/lsst-sqre/ltd-conveyor) built-in so thathttps://github.com/lsst-sqre/ltd-masonisn’t required.Usage and development docs are currently in the README.MIT LicenseCopyright (c) 2017 Association of Universities for Research in Astronomy, Inc.Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.