Details
-
Type:
Story
-
Status: To Do
-
Resolution: Unresolved
-
Fix Version/s: None
-
Component/s: Continuous Integration, Stack Documentation and UX
-
Labels:
-
Team:SQuaRE
Description
The doxygen pages (http://lsst-web.ncsa.illinois.edu/doxygen/x_masterDoxyDoc/annotated.html) currently don't include any of the obs packages (e.g., obs_lsstSim, obs_cfht, obs_subaru). These packages contain useful code, and their documentation should be merged in with that in Doxygen.
This may be difficult, given that we want to keep the obs packages separate in some manner from the rest.
Attachments
Issue Links
- relates to
-
DM-13074 doxygen.lsst.codes master index.html page broken
- Done
Activity
I was trying to separate out all plugins, which might be "official" or might be supported by others, from the main code base. But I could see drawing the dividing line between "official" and "unofficial" instead. I'd rather not fold obs_sst and obs_wiyn into the master build.
My intent was to ensure that we have the tooling to handle an "ecosystem" model with multiple products, some official and some unofficial, relying on common core packages. I worry that the "Borg" model of assimilating all code into a single build (or, worse, repo or package) might be unsustainable.
Hey folks,
FYI I am entering three documentation-related epics in W15 relating to documentation infrastructure/tooling. Step one is to get some agreement on the tooling 
but I think we'd all be surprised at this point if sphinx wasn't involved
I think this ticket is fleshing out a requirement for this work, and unless somebody corrects me I'll revisit this as part of that epic unless it can't wait for some reason?
At this point I am agnostic about the disposition of the obs_ stuff, but I certainly agree that there should be a mechanism for easily dealing differently with "first party" versus "contributed" packages, whether we decide to use it at this point or not. That way we can change our minds later.
I am thinking that if DM-13074 switches from datarel to lsst_distrib as the anchor package that the obs packages would be documented.
I was going to say that this ticket no longer seems to be relevant, but then I realized that obs_subaru still hasn't been added to pipelines.lsst.io
Re KT's comment:
I assume that you mean one documentation product, generated by some toolset (breathe?) that unifies doxygen + sphinx
Is this proposal supposed to cover all products, or only obs packages?
The reason why we use lsstDoxygen is to allow links to packages that you don't depend on (e.g. meas_algorithms can refer to pipe_tasks), and to allow us to generate documentation of peer packages (e.g. the LSST_task_documentation group). Why don't you just want to add the obs_* packages to this master build?