Doxygen python syntax how to#
Doxygen python syntax code#

It’ll be better to have separate Python and C++ API reference sections for each package. In terms of the output context, I’ll push back on putting the C++ API reference on the same HTML page as the Python API reference.

So I’ll backtrack and talk about both separately. I’m not sure, but the quoted passage might be mixing up the authoring context and the generated output context. Last I heard, we were planning to go with Breathe to bridge Doxygen and Sphinx. It might also be nice to have the documentation for both languages on the same page, allowing text that’s relevant for both languages to appear only once. My validate_base package shows this, see. So instead of making a reference with :py:mod:`lsst.afw`Īnd Sphinx will make the appropriate cross-link. This means that in conceptual documentation, and certainly in numpydoc, we can treat the default domain as python. Now it turns out that we can take advantage of Sphinx’s ‘default’ domain. In other words, a person should be able to read the LSST Science Pipeline’s/Stack’s documentation and never be distracted by C++ details.

Doxygen python syntax code#

Example code in numpydoc docstrings is always Python code. Types of parameters and return types will cross-reference to Python APIs. API reference documentation written in Python modules (also known as numpydoc-formatted docstrings) will only refer to other Python APIs and Python concepts. do you know if whatever it does is already consistent with my above recommendations? If it already has a sane approach to this, it’d probably be best to just go with that instead of fighting it.

I also think we should either have a custom directive for linking a C++ code object to its Python counterpart, and possibly try to make those connections automatically. When writing general documentation that isn’t language-specific, use the Python syntax and directives. When documenting C++ code (I’m not sure we’d actually ever do this if we continue to use Doxygen), refer to to other code objects using C++ syntax (double-colon namespaces) and :cpp: directives. When documenting Python code, always refer to other code objects using Python syntax (dotted namespaces) and :py: directives, even if those code objects are originally defined in C++.

Doxygen python syntax how to#

As we start to write more restructured text documentation, I think we need to determine our policy (and perhaps add some tooling) for how to refer to code objects (classes, functions, etc) that exist in both C++ and Python, since Sphinx restructured text provides different syntaxes for those links.