# DM Developer Guide is now published with LSST the Docs **URL:** \ **Category:** DM Notifications\ **Tags:** doc-engineering\ **Created:** [May 27, 2016, 9:03am UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813 "2016-05-27T09:03:25Z")\ **Posts on this page:** 7\ **Page:** 1
**Author:** ![jsick](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jsick/32/672_2.png) [@jsick](https://www.rubin.community/u/jsick)\ **Post date:** [May 27, 2016, 9:03am UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/1 "2016-05-27T09:03:25Z")
The [DM Developer Guide](https://developer.lsst.io) ([https://developer.lsst.io](https://developer.lsst.io)) is now published with LSST the Docs, which I [introduced a couple weeks ago](http://www.rubin.community/t/introducing-lsst-the-docs-for-continuous-documentation-delivery/781?u=jsick). 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](https://github.com/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](https://github.com/lsst-dm/dm_dev_guide/pull/35) ticket branch. It is published at [https://developer.lsst.io/v/DM-5063/](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](https://sqr-006.lsst.io/#versioned-documentation-urls). ### 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](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](https://developer.lsst.io), I’ve enabled [GitHub’s branch protections](https://help.github.com/articles/about-protected-branches/). 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](http://GitHub.com). [You can read more about GitHub’s in-browser workflow on their documentation site.](https://help.github.com/articles/github-flow-in-the-browser/) ### 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](http://www.sphinx-doc.org/en/stable/domains.html#directive-envvar). 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](http://www.sphinx-doc.org/en/stable/ext/intersphinx.html) 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](https://jira.lsstcorp.org/browse/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](https://jira.lsstcorp.org/browse/DM-5895) 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](https://jira.lsstcorp.org/browse/DM-6120). ---
**Author:** ![timj](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/timj/32/10_2.png) [@timj](https://www.rubin.community/u/timj)\ **Post date:** [May 27, 2016, 2:06pm UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/2 "2016-05-27T14:06:53Z")
> [@jsick](#): > > Previously I’ve encouraged some writers to adopt code reference syntax for lsst APIs in anticipation of the LSST Pipelines documentation launch 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? ---
**Author:** ![ktl](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/ktl/32/1373_2.png) [@ktl](https://www.rubin.community/u/ktl)\ **Post date:** [May 27, 2016, 2:24pm UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/3 "2016-05-27T14:24:42Z")
Better to just make the build non-picky until the destinations exist, no change to source needed. ---
**Author:** ![jsick](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jsick/32/672_2.png) [@jsick](https://www.rubin.community/u/jsick)\ **Post date:** [May 27, 2016, 3:50pm UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/4 "2016-05-27T15:50:34Z")
Hi @timj, it’ll be okay. I promise to implement code links once the Pipelines documentation exists. ---
**Author:** ![jsick](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jsick/32/672_2.png) [@jsick](https://www.rubin.community/u/jsick)\ **Post date:** [May 27, 2016, 4:11pm UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/5 "2016-05-27T16:11:19Z")
**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. ---
**Author:** ![jsick](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jsick/32/672_2.png) [@jsick](https://www.rubin.community/u/jsick)\ **Post date:** [May 27, 2016, 10:20pm UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/6 "2016-05-27T22:20:43Z")
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](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. ---
**Author:** ![timj](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/timj/32/10_2.png) [@timj](https://www.rubin.community/u/timj)\ **Post date:** [May 27, 2016, 10:48pm UTC](https://www.rubin.community/t/dm-developer-guide-is-now-published-with-lsst-the-docs/813/7 "2016-05-27T22:48:42Z")
This is great. Thank you for tweaking things so that we can minimize effort on updating downstream and retain semantic markup.