This should be a smooth transition for both readers and writers. Existing links to URLs in the
/en/latest/ version published on Read the Docs should re-direct seamlessly to LTD’s URL scheme.
Since the Developer Guide is our highest-profile document on LSST the Docs, to date, I wanted to clarify a few small points.
Rebase your existing branches; they will be published automatically
If you have a branch in the lsst-dm/dm_dev_guide repo, please rebase it against
master. This will allow your branch to inherit the Travis configuration and be published as an ‘edition’ through LSST the Docs.
Note the ticket name in the path, and that for the moment, a trailing slash is required on the ticket name/branch name. More information about LTD URLs is available in SQR-006.
Seeing the status of your builds
To know when your build has finished, or identify a build failure, you’ll want to monitor the Travis CI status. There are two ways to do this
- Open a pull request early on; the PR page will show your branch’s current build status.
- View the Travis dashboard at https://travis-ci.org/lsst-dm/dm_dev_guide/branches
The master branch is protected
To give you reassurance that any changes you make to the Developer Guide won’t accidentally break the main edition published at https://developer.lsst.io, I’ve enabled GitHub’s branch protections. This means
- You can’t push directly to
master; you’ll always need to create a branch first.
- The Travis build for that branch will need to succeed before you can merge to master.
- Your branch needs to be up-to-date with
git rebaseif it isn’t) before merging.
Going through a branch might sound like a pain to you, but I promise it isn’t! Thanks to GitHub, you can create a new branch, make commits to files, make a pull request, and merge your change all from the browser—no cloning necessary. So in fact, LTD’s automatic branch publishing combined with Travis’ checks means you can reliably make changes to the Developer Guide from GitHub.com. You can read more about GitHub’s in-browser workflow on their documentation site.
Strict settings for Sphinx builds
In this new publishing workflow, I’ve switched to building the Developer Guide in ‘nit-picky’ mode. This means that broken references will now become errors. Doing this helps us make better use of Travis for ensuring that the Developer Guide is healthy. Before, an intended link to a code API could silently fail; now, you’ll know.
This has lead to two types of changes for Developer Guide contributors:
envvarrole can now only be used if there’s an associated environment variable reference directive. Previously I thought
envvaronly existed for semantics, but in fact it’s there for making links. I’m sorry for misleading people about this. I’m in the process of updating the reStructuredText documentation.
- Code links via intersphinx should only be made to code documentation that exists (like for Astropy, Numpy or the Python standard library). Previously I’ve encouraged some writers to adopt code reference syntax for
lsstAPIs in anticipation of the LSST Pipelines documentation launch. Unfortunately you’ll have to hold-off on the reference syntax until that documentation is available. Sorry again.
It’ll get better
There are few details we got accustomed to on Read the Docs that haven’t made it to LSST the Docs yet. Here are some of the planned improvements so you’ll know what to expect in the coming months:
- You currently need to append ‘
/’ to directory names in URLs. This will be fixed in DM-5894.
- Although it’s fairly straightforward to turn branch names into URLs, I certainly don’t want that to be the primary way edition URLs are discovered. Watch DM-5859 for the introduction of dashboards for editions/builds, as well as version-switching interface elements that will be embedded in the Developer Guide itself.
- We’ve temporarily lost the ‘Edit on GitHub’ button. I’ll come back very soon in DM-6120.