[doc] Fixathon 2: documentation sprint by siliataider · Pull Request #22289 · root-project/root

siliataider · 2026-05-13T15:20:55Z

Cleanup, refactoring, cheat sheets, etc.

Changes summary

General

Remove source files from doxygen groups (\file xxx \ingroup yyy). These clutter the overview without adding useful documentation.
Remove/reorder groups that are used infrequently.
Enable inlining of inherited functions into the overview list. This significantly simplifies viewing/searching the available interface of a class.

Python Interface

Updated the dedicated Python Interface top-level section in the Doxygen navigation, with a landing page covering installation, quickstart and a quick overview
Added a new structured RDataLoader page walking users through data preparation, loader configuration, batch iteration etc.
- TODO: Eventually add the actual docstrings of the public facing classes instead of the custom reference table I created
Revamped the UHI page with an updated intro and a new Serialization section
Added two cheat sheets (RDataLoader and UHI) as a proof of concept (one-page PDF references downloadable and embedded directly in the docs too)
- TODO: update the UHi cheatsheet to make the plotting section more prominent
- TODO: once enough cheat sheets exist, refactor them into a dedicated Cheat Sheets index page

Search Engine

No changes for the moment

Preview

See a preview of the doxygen page here:
https://root.cern/doc/hackathon/index.html

Note: This webpage does not contain the full doyxgen run. Macros embedded in the source code are not being run.

ferdymercury

Thanks a lot for this endeavor!

Two remarks

QHP generation shouldn't be disabled for main Doxyfile since it's used to publish qch file which is fundamental for qtcreator IDE
it would be a lot cleaner if you used, as ALICE O2, this approach: #17426 rather than having two huge Doxyfiles almost impossible to review and annoying to maintain with warnings depending on version, etc

ferdymercury · 2026-05-14T11:21:43Z

 # This tag requires that the tag GENERATE_HTML is set to YES.

-GENERATE_QHP           = YES
+GENERATE_QHP           = NO


Suggested change

GENERATE_QHP = NO

GENERATE_QHP = YES

OK, we won't touch it. I thought nobody uses this. 😅

:) thanks
It's nice because it allows you press F1 in the IDE:
https://user-images.githubusercontent.com/10653970/154870916-28e4009d-eb70-46df-a52b-da81cfe3c97f.png
and that works also offline / no need to open web browser

- Move the web widgets to the webdisplay group. - Move webdisplay to GUI group. - Put the parametric functions group under Math. - Regroup I/O doxygen groups. - Move doxygen GUI group to Graphics Co-authored-by: martinfoell <m.foell.1999@gmail.com>

- Remove internal and detail classes from RDF group. - Remove source files from RDF group. - Expand docs of RDataFrame overview page. - Structure documentation of RDataFrame API.

…xygen group. Listing files on the doxygen page doesn't have a lot of benefit. Instead, we will list the contained classes.

- Enable sorting of groups in the treeview - Enable right-hand side scrolling site overview - Add "make preview" for a fast preview mode without ROOT customisations, with MT processing, and without dot graphs - Enable inlining of inherited members into the overview of class functions

vepadulano

Thank you for all of this work! I have reviewed the Python part of the PR, here are some comments from my side.

vepadulano · 2026-05-15T14:01:06Z

+\htmlonly
+<div class="install-tabs">
+  <div class="tab-buttons">
+    <button class="tab-btn active" onclick="switchTab(this, 'conda')">conda</button>


As we were discussing during the hackathon, this is quite cool to have in the doxygen pages! Would be nice to have this in some compact form that can be used in other places, not for this PR

vepadulano · 2026-05-15T14:04:07Z

+# Write it to a ROOT file
+with ROOT.TFile.Open("output.root", "RECREATE") as f:
+    h.Write()


nitpick, I would prefer we showed f.WriteObject(h, "name_of_histo"). My reasoning is that RFile will not support the syntax object.Write because there will be no implicit object registration anyway. I do see the point of WriteObject needing the extra string argument (which could even be defaulted to h.GetName() internally for TObject-derived objects). So this is mostly to voice my opinion, I will accept what the majority prefers

vepadulano · 2026-05-15T14:04:43Z

+# Define a column x
+rdf = rdf.Define("x", lambda : np.random.normal(0, 1))


We know that this syntax will be raising a warning for a while now, until we enable pure Python callables in RDF. Perhaps best not to show it already?

vepadulano · 2026-05-15T14:10:35Z

+# Define a Python callback to compute a new variable
+def invariant_mass(E: float, p: float) -> float:
+    return math.sqrt(E**2 - p**2)


Similar comment here about the implicit numba-jit API

vepadulano · 2026-05-15T14:13:13Z

+# events with fewer than 10 jets are zero-padded
+~~~
+
+\warning Every RVec column in `columns` must appear in `max_vec_sizes`.


Suggested change

\warning Every RVec column in `columns` must appear in `max_vec_sizes`.

\warning Every vector column in `columns` must appear in `max_vec_sizes`.

unless we really only support RVec?

vepadulano · 2026-05-15T14:13:46Z

+optimizer = torch.optim.Adam(model.parameters())
+
+for epoch in range(num_epochs):
+    for X, y in dl.as_torch():


Any reason for the X to be capitalised?

vepadulano · 2026-05-15T14:15:31Z

+
+### Eager loading
+
+By default the loader reads data lazily, one chunk of data at a time. For small datasets that fit in memory and will be iterated many times, eager loading pays a one-time cost at construction and then serves every epoch from memory:


Suggested change

By default the loader reads data lazily, one chunk of data at a time. For small datasets that fit in memory and will be iterated many times, eager loading pays a one-time cost at construction and then serves every epoch from memory:

By default the loader reads data lazily, one chunk of data at a time. For small datasets that fit in memory and will be iterated many times, eager loading pays a one-time cost at construction and then serves batches in every epoch from memory:

vepadulano · 2026-05-15T14:15:53Z

+    loss = (loss_fn(model(X), y) * w).mean()
+~~~
+
+### Eager loading


Perhaps I would move this section further up since it's referenced before by the resampling section

vepadulano · 2026-05-15T14:16:16Z

+
+## API Reference
+
+### RDataLoader(rdataframes, ...)


This is nice, but it would be nicer if this was a full doxygen function doc like https://root.cern/doc/master/group__Pythonizations.html#ga7fd79fcb9358768e7b5f9fe0a924dd77

github-actions · 2026-05-15T14:52:34Z

Test Results

22 files 22 suites 3d 14h 48m 10s ⏱️
3 849 tests 3 849 ✅ 0 💤 0 ❌
76 030 runs 76 030 ✅ 0 💤 0 ❌

Results for commit cf59381.

siliataider requested review from bellenot, couet, dpiparo, guitargeek, hageboeck, jblomer, linev, martamaja10, pcanal and vepadulano as code owners May 13, 2026 15:20

siliataider assigned siliataider and hageboeck May 13, 2026

siliataider marked this pull request as draft May 13, 2026 15:22

siliataider assigned silverweed and martinfoell May 13, 2026

siliataider added in:Documentation in:I/O in:Python Interface in:RDataFrame in:Hist in:ML Everything under ROOT/ML labels May 13, 2026

siliataider changed the title ~~Fixathon docs~~ [doc] Fixathon 2: documentation sprint May 13, 2026

siliataider force-pushed the fixathon_docs branch from 5db0a05 to c114459 Compare May 13, 2026 15:59

ferdymercury suggested changes May 14, 2026

View reviewed changes

siliataider force-pushed the fixathon_docs branch from c114459 to b397b7e Compare May 15, 2026 07:47

[doxygen-infra] Call the main page "main page" in the navigation tree.

dcf02fb

hageboeck force-pushed the fixathon_docs branch from b397b7e to f809570 Compare May 15, 2026 12:19

hageboeck added the clean build Ask CI to do non-incremental build on PR label May 15, 2026

[doxygen] Fix doxygen warnings.

1984c7f

hageboeck and others added 13 commits May 15, 2026 14:38

[doc] Rename Core ROOT classes

104463d

[doxygen-dataframe] Overhaul RDataFrame doxygen group

1ad2120

- Remove internal and detail classes from RDF group. - Remove source files from RDF group. - Expand docs of RDataFrame overview page. - Structure documentation of RDataFrame API.

[doxygen-files] Remove RNTuple source files from the corresponding do…

9cafe2d

…xygen group. Listing files on the doxygen page doesn't have a lot of benefit. Instead, we will list the contained classes.

[doc][Python] Move the Python Interface section to top level

8995be3

[doc][Python] Add the Getting started page

cd7964f

[doc][Python] Add ML cheat sheet and doc page

633013e

[doc][Python] Update ML section

0652444

[doc][Python] Update getting started section

b0a79db

[doxygen-groups] Extend the description of the RVec group.

041c976

[doxygen] Remove file documentation pages from doxygen groups.

79a896f

[doc][Python] Add UHI cheatsheet and update section

81c756d

hageboeck force-pushed the fixathon_docs branch from f809570 to cf59381 Compare May 15, 2026 12:39

siliataider marked this pull request as ready for review May 15, 2026 14:19

vepadulano requested changes May 15, 2026

View reviewed changes

		# Define a column x
		rdf = rdf.Define("x", lambda : np.random.normal(0, 1))

	\warning Every RVec column in `columns` must appear in `max_vec_sizes`.
	\warning Every vector column in `columns` must appear in `max_vec_sizes`.


		### Eager loading

		By default the loader reads data lazily, one chunk of data at a time. For small datasets that fit in memory and will be iterated many times, eager loading pays a one-time cost at construction and then serves every epoch from memory:

Conversation

siliataider commented May 13, 2026 • edited by hageboeck Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes summary

General

Python Interface

Search Engine

Preview

Uh oh!

ferdymercury left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vepadulano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 15, 2026

Test Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

siliataider commented May 13, 2026 •

edited by hageboeck

Loading