Doc

[jrouquie]

This is a documentation only PR.

Populate the pages

• https://libsemigroups.github.io/HPCombi/annotated.html
• https://libsemigroups.github.io/HPCombi/files.html

Add introductory text on main Doxygen page.
Remove some repetitions.
Plus smaller stuff.

[james-d-mitchell]

Thanks for the PR @jrouquie, could you maybe say a few words about what changes you've made and why please?

[hivert]

Hi James. @jrouquie is a potential "real world" user of HPCombi. To learn how to use it, he is reading the doc and obviously find a lot of place to improve it. In particular, for different implementation of the same function, I copied with @copydoc the doc. It is indeed better to have only one doc and all the other saying that this is a different implementations of the same functionality.

[slel]

In README.md, line 8, "compiler" should be "compilers".
One could rephrase the sentence and reflow as follows.

 High Performance Combinatorics in C++ using vector instructions v1.0.1

 HPCombi is a C++17 header-only library using the SSE and AVX instruction sets,
-and some equivalents, for very fast manipulation of small combinatorial objects such
-as transformations, permutations, and boolean matrices. The goal
-of this project is to implement various new algorithms and benchmark them on
-various compiler and architectures.
+and some equivalents, for very fast manipulation of small combinatorial objects
+such as transformations, permutations, and boolean matrices. HPCombi implements
+new algorithms and benchmarks them on various compilers and architectures.
```

[james-d-mitchell]

Thanks @jrouquie, I've just rebased this onto main after fixing the ci in #45.

[james-d-mitchell]

Thanks for this @jrouquie, this is a big improvement to the documentation. Except for the minor comments in the review, can you also please run clang-format on every *.*pp file that you've touched in this PR? Then we can merge this.

[james-d-mitchell]

Seems to me that it might be better to just include README.md file as we were previously here, otherwise there's a good chance that the contents of this section and the README.md will become out of sync of over time. Was there a reason for having both? Might it not be better to just update README.md to include the extra material that's included here?

[jrouquie]

The contents of this section and the README.md contain distinct information, without repetition. There is no need to check for synchronization. No risk of out of sync.

Indeed, that was precisely the point of this modification : do not copy paste, do not let the reader notice (after having wasted some time) that they have already read this file. Avoid circular link where https://libsemigroups.github.io/HPCombi/ advises to go read "The Doxygen auto generated API" and actually points to itself.

Alternatively one could move the contents of "/*! \mainpage HPCombi" (in hpcombi.hpp) into the readm, and in the main page of the Doxygen doc just point to the readme (instead of duplicating it). I prefered to separate the authors/contributors/thanks list and the technical information, but feel free to implement this alternative solution.

[james-d-mitchell]

Thanks, that makes perfect sense.

[james-d-mitchell]

Looks good to me. Ok to merge @hivert ?

[hivert]

Looks good to me. Ok to merge @hivert ?

Looks good to me too ! Please merge it if you have the time. Otherwise I'll do it next week.