Details
-
Type:
Story
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: Stack Documentation and UX
-
Labels:
-
Story Points:4.8
-
Epic Link:
-
Team:SQuaRE
Description
The pipelines.lsst.io build tool will coordinate builds of the pipelines.lsst.io Sphinx site. Its main functionality is:
- Symlink doc/ directories of packages into a pipelines.lsst.io clone
- Add configuration information (like the current tag, or if working on master, the branches and most recent tag)
- Run the Sphinx build
Some of this functionality is already coded in LTD Mason, however, it should be moved to https://github.com/lsst-sqre/documenteer, our core package for DM Sphinx projects. (I'm slowly breaking LTD Mason apart; I think having a single package that was both an LTD upload tool and a build tool was a wrong fit).
Attachments
Issue Links
Activity
Hey Simon Krughoff, would you be willing to review this?
The ticket primarily consists of a PR in the documenteer package to provide a build-stack-docs command line tool that performs doc directory linking into the pipelines_lsst_io project directory and runs a Sphinx build (directly with Sphinx's Python API).
https://github.com/lsst-sqre/documenteer/pull/14
While implementing the build tool I realized two things:
1. It'd be good to have documented oriented around packages (Git repos) in addition to documentation organized around Python modules. This is particularly important for non-code packages (like data packages, or verify_metrics).
2. The build will be more reliable if we have a manifest.yaml file in the doc directories of packages that declares what package, module and _static/ directories should be symlinked into pipelines_lsst_io.
I've created a PR to DMTN-030 that describes these new design decisions.
I'm at DESC this week, but I'm willing to do it if you can absorb a little latency.
That's fine, thanks!
This looks great. I have a few comments, but nothing substantial enough to prevent merging.
Thanks for the comments Simon Krughoff! I've fixed them all and pushed the code as documenteer 0.2.
I've written a summary of https://community.lsst.org/t/dmtn-030-science-pipelines-documentation-design-technote/1520/5?u=jsick
This build tool is needed before pipelines.lsst.io's structure (designed in https://dmtn-030.lsst.io) can be stubbed out. We anticipate that most content, even in the Processing and Frameworks sections, will originally come from stack package's doc directories.