Skip to content

Commit

Permalink
update pythonizations docs to use pythondoc
Browse files Browse the repository at this point in the history
  • Loading branch information
m-fila committed Nov 27, 2024
1 parent 325a457 commit 51c5bf0
Showing 1 changed file with 7 additions and 19 deletions.
26 changes: 7 additions & 19 deletions for_developers/docs/pythonizations.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,27 +7,15 @@ sidebar:
nav: "for_developers"
---

Some ROOT classes have *pythonizations* that require additional documentation. These can be added as special boxes to the rendered Doxygen page of their corresponding C++ class. As an example, see the Python-specific [RDataFrame](https://root.cern/doc/master/classROOT_1_1RDataFrame.html#python) docs. This documentation is written in the pythonization files corresponding to the original C++ class, which can be found in `<root_sources>/bindings/pyroot/pythonizations/python/ROOT/_pythonization`. Documentation is added as a module-level docstring, which should following the template below, replacing `{CLASS_NAME}` with the corresponding C++ class name, `{BLOCK_TITLE}` with the title of the documentation block (in most cases, "PyROOT" is used) and `{DOCUMENTATION_BODY}` with the documentation body, which supports the usual Doxygen tags and other formatting methods (see also the [documentation formatting tips]({{'for_developers/docs/useful_tips' | relative_url}})).
Some ROOT classes have *pythonizations* that require additional documentation. These can be added as special boxes to the rendered Doxygen page of their corresponding C++ class. As an example, see the Python-specific [RDataFrame](https://root.cern/doc/master/classROOT_1_1RDataFrame.html#python) docs. This documentation is written in the pythonization files corresponding to the original C++ class, which can be found in `<root_sources>/bindings/pyroot/pythonizations/python/ROOT/_pythonization`.
Documentation is added as a module-level docstring, which should follow the template below. Replace `{CLASS_NAME}` with the corresponding C++ class name and `{DOCUMENTATION_BODY}` with the documentation body. The documentation body supports standard Doxygen tags and other formatting methods (see also the [documentation formatting tips]({{'for_developers/docs/useful_tips' | relative_url}})).

```
r"""
/**
\class {CLASS_NAME}
\brief \parblock \endparblock
\htmlonly
<div class="pyrootbox">
\endhtmlonly
\anchor python
## {BLOCK_TITLE}
r'''
\pythondoc {CLASS_NAME}
{DOCUMENTATION_BODY}
\htmlonly
</div>
\endhtmlonly
*/
"""
\endpythondoc
'''
```

The `\anchor` tag adds a permalink to the PyROOT box on rendered documentation page, allowing for easy linking to the Python-specific documentation by appending `#python` to the URL of the doxygen page (i.e., [https://root.cern/doc/master/classROOT_1_1RDataFrame.html#python](https://root.cern/doc/master/classROOT_1_1RDataFrame.html#python)).
The documentation added this way can be directly linked to by appending `#python` to the URL of the doxygen page (i.e., [https://root.cern/doc/master/classROOT_1_1RDataFrame.html#python](https://root.cern/doc/master/classROOT_1_1RDataFrame.html#python)).

0 comments on commit 51c5bf0

Please sign in to comment.