feat(docs): add complete C++ API reference

[HaoZeke]

Try them out here: https://github.com/metatensor/metatomic/actions/runs/21580495763/artifacts/5339250994

Before:

Which may bring up more questions than answers in terms of the actual implementation.

Now also has:

To be fair it's a bit meh here since these are basically empty, but still nice to see IMO.

FWIW this is basically "imagine if showcode in the Python worked for the C++ bits"

Contributor (creator of pull-request) checklist

• Tests updated (for new features and bugfixes)?
• Documentation updated (for new features)?
• Issue referenced (for PRs that solve an issue)?

Reviewer checklist

• CHANGELOG updated with public API or any other important changes?

[Luthaf]

Sorry, we are not adding a new tool to the doc stack. Can this be made to work inside sphinx/tox?

[HaoZeke]

Could probably rewrite it in bash, yes, it's just a shell script :D

[Luthaf]

Looking at the docs generated in CI, I don't find this better than the existing setup =/.

• there are no links from types used as parameters to the types definition/documentation (NeighborListOptions and TensorBlock below)

• I find the change to "block-style" code (instead of inline) every other line very distracting
• there is no organisation of the documentation, stuff appear in the order it is defined in the header files, which is not necessarily the best order to explain/introduce things

I though this tool was about adding a link to the existing sphinx things to "click here to open the code for this function/class", which would work for me.

[HaoZeke]

...

(agreed)

I though this tool was about adding a link to the existing sphinx things to "click here to open the code for this function/class", which would work for me.

Yup, that's the plan, lemme draft this and get back to it next weekend :D