Before I formally RFC aspects of the new doc platform, I wanted to be sure I understood how each team in DM was documenting their source code and APIs so I could be sure I accommodated everyone.
Known languages:
C++. Uses doxygen that can be handled with breathe.
Python. Uses doxygen or ‘native’ docstring formats that breath/numpydoc/sphinx can handle.
@jsick SUI/T team is new in the JS document. We would love to hear your suggestions. We have been using JavaDoc to do some documentation for code. Since the APIs will be used by the science and development community, I think we should have plan for changes once we get some feedback.
For Python I would say that we use doc strings and we prefer that those doc strings include Doxygen markup commands (and if so, start with """!).
It is possible to add Doxygen markup to Python code without using doc strings (and some ancient bits of our Python do that) but we discourage this because it is non-standard and incompatible with Python’s standard help tools.
Interesting, this is the first I’ve heard of a desire to keep doxygen markup in Python.
Would you be open to a gradual transition where we continue to support doxygen-marked up Python with, say, numpydoc, slowly taking over? Or are you hoping we stay with doxygen Python forever?
I was only trying to clarify what we are doing now. I don’t personally care very much what documentation system we use as long as it is produces good documentation and is readable in the source code. You made a good case for using numpydoc at the All Hands Meeting and I thought we agreed to go that route. I am not suggesting we revisit that decision.
They aren’t really other languages, but we do have some very important documentation that’s held as strings in various data structures:
afw.table.Schema objects hold descriptions of the columns in all of our output tables
pex.config.Config objects hold descriptions for essentially all of our configuration parameters
At some level, this needs to be dynamic. For instance, you can get different Schemas depending on what pipeline you run and how you configure it, and extension packages that aren’t part of the mainline stack will frequently add new columns. The same is perhaps even more true for configuration. But I think it’d be very valuable to find a way to include a standard version of the configuration hierarchy and the Schemas of a few important output tables in along with the rest of the API documentation. That would probably require some custom code to load those objects from CI outputs (or something similar) and generate pretty documentation from it.