Jonathan Sick walked us through LSST the Docs - what it is (what it's doing right now and what it will do) and how we will use it. 

 

My takeaway: 

LSST the docs (LTD) will be a very cool publishing platform for LSST, which will let you write technotes (in rst), documents (in latex), stand-alone python repositories, and code documentation (sphinx, sphinx + doxygen), and have it published to the web in a seamless process that also allows you to have multiple versions of each of these items.  Examples: documentation of your code, plus documentation for a particular branch (or older version), or technotes that are in draft / stable / in-update versions, and which you can point your coauthors or users toward.  The code documentation will allow API documentation which requires building the LSST software stack (not possible as part of Read The Docs). 

Currently, LTD is ramping up and is mostly holding technotes and a few documents (LDM-151). In the F16 cycle, there will be significant updates to LTD, including letting users set up their own LTD sites automatically. For now, contact Jonathan when you're ready to set up a new project for LTD. 

LTD uses travis to ensure that builds work; there is some setup to direct travis how to work. LTD-mason takes charge of this process (building with travis and publishing to the web) so be sure to read those notes about LTD-mason. LTD-keeper is (at least for now) primarily something SQuaRE needs to worry about - it tracks where LTD-mason publishes things (into the S3 bucket) and then controls how people access the resulting webpages (what the URL looks like). 

 

 

The announcement of LSST the docs, with much more information about what's behind LSST the docs is here https://community.lsst.org/t/introducing-lsst-the-docs-for-continuous-documentation-delivery/781. There is also a technote that includes some of the future plans here https://sqr-006.lsst.io/
Technotes (sims technotes: https://community.lsst.org/t/listing-of-available-sims-technotes/619/1), the developer guide (http://developer.lsst.io/en/latest/index.html), and soon-to-be-written science pipeline user guides are migrating to the official LSST the docs platform. Code documentation is another area that will be migrating to LSST the docs (you can peek at our very rudimentary MAF documentation here https://sims-maf.lsst.io/ )
Comments from Jonathan:
- SQR-006 shows a simple Sphinx project: https://github.com/lsst-sqre/sqr-006/blob/master/.travis.yml
- LTD-Keeper is an example of combining code testing with doc builds: https://github.com/lsst-sqre/ltd-keeper/blob/master/.travis.yml
- An example of hosting a LaTeX project: https://github.com/lsst/LDM-151/blob/master/.travis.yml
Docs on the Travis setup are at https://ltd-mason.lsst.io/travis.html Note that I can help you set up your project (software doc, technote, etc.) to publish through Travis.
For EUPS-based software docs, I've outlined the process here: https://sqr-006.lsst.io/#ltd-mason-for-multi-repository-eups-documentation-projects
Publishing docs for EUPS projects is still experimental, and requires collaboration with Josh Hobblit to get it set up on LSST DM's Jenkins CI.
  • No labels