Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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)).