Krzysztof Findeisen, here's the Pipelines C++ reference generate through breathe and organized by breathe-apidoc.

https://pipelines.lsst.io/v/DM-22499/index.html#reference-and-indices

Of principal use is the namespace listing: https://pipelines.lsst.io/v/DM-22499/cpp-api/namespacelist.html

And the class listing: https://pipelines.lsst.io/v/DM-22499/cpp-api/classlist.html

The output overall seems better than what exhale was trying to do, but overall there is still a duplication of content between comprehensive namespace listings (e.g. https://pipelines.lsst.io/v/DM-22499/cpp-api/namespace/namespacelsst_1_1afw_1_1typehandling.html#_CPPv4I0EN4lsst3afw12typehandling10GenericMapE) and standalone pages for classes (e.g. https://pipelines.lsst.io/v/DM-22499/cpp-api/class/classlsst_1_1afw_1_1typehandling_1_1_generic_map.html

I noticed that the GenericMap docs still suffer from that parsing/rendering area with "A Key" where "Key" becomes automatically linked.

What do you think about this solution? Thanks for your thoughts.

Hmm... while the styling might be better, I think the breathe-apidocs are much more badly corrupted than the exhale ones:

• The namespace listings seem more confusingly organized than in exhale – the afw::typehandling listing has some garbling (UnsupportedOperationException is blended with operator<<(Storable)), and, like in exhale, I can't always get from the namespace page to the class pages.
• I don't see any listing of class methods or other members for typehandling::GenericMap, table::detail::SchemaMapperImpl, or ip:diffim::DipoleFluxAlgorithm, though I do for typehandling::Key
• I see some apparently corrupted entries in the namespace list, like "lsst::afw::image::@152". I think these might be anonymous namespaces.

I really can't recommend this version; not only does it have many of the same navigation problems as exhale, there's just too much information missing.

On the plus side, the search feature nicely shows the class pages as the first results, and distinguishes clearly between the C++ and Python APIs. Though it's a bit weird to get separate results for lsst.afw.typehandling.GenericMap and GenericMap, or for Class lsst::afw::typehandling::GenericMap and Template Class GenericMap.

On a note unrelated to this ticket, I'm not sure I like the global task index. Some tasks (e.g., ConfigApdbLoader and DirectApdbLoader, some of the ip_diffim tasks) are specifically designed to be used as subtasks and don't make sense as an entry point to the Stack as a whole. Could we get an opt-out class decorator or something?

Ok, thanks for your review of the breathe output. We'll go back to the drawing board.

On a note unrelated to this ticket, I'm not sure I like the global task index. Some tasks (e.g., ConfigApdbLoader and DirectApdbLoader, some of the ip_diffim tasks) are specifically designed to be used as subtasks and don't make sense as an entry point to the Stack as a whole. Could we get an opt-out class decorator or something?

It's just an index; it's not the curated data processing guides that we're building (i.e. https://dmtn-030.lsst.io/#processing-topic-type). I certainly agree its a bad entrypoint for normal use cases, but it's what we have at this point in the Construction Project.

I'm going to mark this work as "Done" as in, we've proven that the breathe-apidoc approach is not suitable for pipelines.lsst.io. For archival reference, I've attached the git patches to https://github.com/lsst-sqre/documenteer and https://github.com/lsst/pipelines_lsst_io to this ticket. The draft of the built documentation currently remains at https://pipelines.lsst.io/v/DM-22499

Going forward, I think that DM-23094 (doxylink) is our best bet.