![]() #DOXYGEN PARAM TYPE PYTHON CODE#This is consistent with keeping API reference documentation where the code is, and eliminating duplicate content.Īt the same time, I’m not entirely sure how or if this will work. Here, I think you’re right: it’d be ideal to document a C++ API in the C++ header itself, and then transform that C++ reference automatically into a Python API reference. I’ll especially have to study what pybind11 means for this. Note that this link between C++ and Python API reference pages will be custom work I’m not sure I know how this will be done yet. But again, I think we should strive to allow Python API users to be able to not see any mention of C++ in documentation. The API reference pages will include ‘see also’ cross-links that will allow someone to jump from the Python version of an API to the C++ version of the API. 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. 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 PARAM TYPE PYTHON 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. ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |