DM Developer Guide is now published with LSST the Docs

Data Management DM Notifications
#1

The DM Developer Guide (https://developer.lsst.io) is now published with LSST the Docs, which I introduced a couple weeks ago.

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.

As an example, I have a tickets/DM-5063 ticket branch. It is published at https://developer.lsst.io/v/DM-5063/.

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

  1. Open a pull request early on; the PR page will show your branch’s current build status.
  2. 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

  1. You can’t push directly to master; you’ll always need to create a branch first.
  2. The Travis build for that branch will need to succeed before you can merge to master.
  3. Your branch needs to be up-to-date with master (you can git rebase if 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:

  • The envvar role can now only be used if there’s an associated environment variable reference directive. Previously I thought envvar only 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 lsst APIs 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.
#2

This is really disappointing and is going to be a real pain and this should have almost blocked the release until we sorted it out. Going through and destroying all the semantically correct markup of :class: and :func: and :meth: usage and replacing them with double backticks is a bad solution because you can’t automate the reverse step of fixing it all up again (and I’m not just saying that because I’ve got to remove all the mark up I had just written yesterday). I assume it wasn’t possible to provide transitional :lclass: etc variants that would allow us to trivially update the dev guide when LSST code docs are available?

#3

Better to just make the build non-picky until the destinations exist, no change to source needed.

#4

Hi @timj, it’ll be okay. I promise to implement code links once the Pipelines documentation exists.

#5

Update: I’ll go ahead with the ‘mock’ Python referencing roles as a temporary stand-in for :meth:, :func:, :mod:, :class:, etc. And update existing object references accordingly.

#6

Hi @timj and others, I’ve merged a set of mock roles into documenteer, and thus the Developer Guide, to enable future-proof semantic code referencing.

See https://github.com/lsst-dm/dm_dev_guide/pull/38 for a brief description and example usage. Official documentation on these new roles is forthcoming.

#7

This is great. Thank you for tweaking things so that we can minimize effort on updating downstream and retain semantic markup.