📝 Add documentation for ZX-calculus package and C++ API docs setup

[pehamTom]

Description

This PR introduces documentation for the C++ ZX-calculus library.
It also adds the general infrastructure for C++ API documentation as part of the MQT Core project based on Doxygen and the breathe extension.

Fixes #813

This change addresses concerns about missing documentation that came up in the revision openjournals/joss-reviews#7478.

Checklist:

• The pull request only contains commits that are related to it.
• I have added appropriate tests and documentation.
• I have made sure that all CI jobs on GitHub pass.
• The pull request introduces no new warnings and follows the project's style guidelines.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.3%. Comparing base (2c02f80) to head (9c7cb09).
Report is 1 commits behind head on main.

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #817   +/-   ##
=====================================
  Coverage   92.3%   92.3%           
=====================================
  Files        127     127           
  Lines      13556   13555    -1     
  Branches    2086    2086           
=====================================
+ Hits       12520   12522    +2     
+ Misses      1036    1033    -3     

Flag	Coverage Δ
cpp	92.1% <100.0%> (+<0.1%)	⬆️
python	99.7% <ø> (ø)

Files with missing lines	Coverage Δ
...nclude/mqt-core/datastructures/SymmetricMatrix.hpp	100.0% <ø> (ø)
include/mqt-core/dd/CachedEdge.hpp	84.2% <ø> (ø)
include/mqt-core/dd/ComputeTable.hpp	100.0% <ø> (ø)
include/mqt-core/dd/Edge.hpp	94.1% <ø> (ø)
include/mqt-core/dd/Operations.hpp	75.5% <ø> (ø)
include/mqt-core/dd/Package.hpp	96.8% <ø> (+<0.1%)	⬆️
include/mqt-core/dd/UniqueTable.hpp	97.1% <ø> (ø)
include/mqt-core/ir/QuantumComputation.hpp	100.0% <ø> (ø)
include/mqt-core/ir/operations/Expression.hpp	92.7% <100.0%> (ø)
include/mqt-core/qasm3/Exception.hpp	53.8% <ø> (ø)
... and 8 more

... and 1 file with indirect coverage changes

[burgholzer]

These look phenomenal ✨ many thanks for taking the time to add these docstrings!
I just browsed through them and added a couple of inline comments where I noticed that something might be slightly off. Hope these help.

Looking forward to seeing this in the online documentation!

[burgholzer]

Alright. I played around with this a little more, tweaked a couple of things, and fixed a couple of smaller errors in the guide as well the general documentation.

To be honest, I am not yet fully happy with the Doxygen+Breathe solution here for the C++ API docs. Mostly because the resulting documentation lacks a lot of the structure that Doxygen actually provides in their HTML standalone builds and which I like very much.
However, I spent much more time today than I am willing to admit to find better alternatives, without much success. It seems that this is the current best practise for how to do this kind of documentation and better tooling needs to be developed first.

And regardless of whether this is the "perfect" solution, it is a big step forward in terms of documentation for the project and this PR most definitely has fulfilled its purpose.
I especially like the short, but on point, quickstart guide here.

Long story short: thank you for your work on this 🙏🏼. let's get it in now 🚀
Polishing the source code documentation and its presentation will be an ongoing effort over the coming weeks and months 🙌🏼