Documentation: proteus-doc -> proteus

[tridelat]

This PR brings the changes to documentation from proteus-doc to proteus, keeping commit authorship (but could not keep the date/time of changes due to some conflicts).

The reason for bringing back the documentation here is that it seems easier to have an automatic way to build it if it is centralised on this repo, see #1040

This should not be squashed and merged (regular merge)

[codecov]

Codecov Report

Merging #1041 into master will increase coverage by <.01%.
The diff coverage is 19.29%.

@@            Coverage Diff             @@
##           master    #1041      +/-   ##
==========================================
+ Coverage   48.89%    48.9%   +<.01%     
==========================================
  Files         514      514              
  Lines      100018   100021       +3     
==========================================
+ Hits        48907    48911       +4     
+ Misses      51111    51110       -1

Impacted Files	Coverage Δ
proteus/mprans/BoundaryConditions.py	0% <0%> (ø)	⬆️
proteus/BoundaryConditions.py	0% <0%> (ø)	⬆️
proteus/tests/test_boundaryconditions.py	97.33% <100%> (-0.25%)	⬇️
proteus/Comm.py	81.17% <100%> (+0.22%)	⬆️
proteus/NumericalFlux.py	38.55% <100%> (+0.18%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 738f837...9ae3070. Read the comment docs.

[cekees]

Looks good. Can you fix the class hierarchy graphs? https://erdc.github.io/proteus-doc/api/proteus.LinearSolvers.html versus https://proteustoolkit.org/api/proteus.LinearSolvers.html

Also, on the Python API doc's, we might want to put the submodules before the sub-packages, or at least limit the depth of the subpackage table of contents so the subpackage section is brief. https://erdc.github.io/proteus-doc/api/proteus.html

[tridelat]

@cekees this is ready to be reviewed/merged (not squashed and merged so that people keep authorship of the documentation they modified).
It will not change the documentation website, just update the files so that the next time we update the docs, we get something like this: https://tridelat.github.io/proteus/
(I pushed the website generated from this branch on my fork)

[tridelat]

@cekees as a side note, clicking on "Python API" leads you to this page: https://tridelat.github.io/proteus/api/modules.html, where you need to click on "proteus package" to actually access the API doc. This can be bypassed to access the proteus doc directly, although having it this way is "safer" if one day an extra package is installed side-by-side with proteus, as it would appear on that intermediate page.

[cekees]

Found a few more issues: 1) the readthedocs template is not scaling the inheritance graphs properly, 2) the C++ docs are not showing ineritance graphs at all, and 3) the C++ docs aren't including the mathematical formulas that have been formatted for doxygen.

[tridelat]

@cekees for 1) I will need to dig a little bit,
for 2) and 3) it looks like the only way is to switch back to doxygen only, and not use breathe.
I think it might be best to just use doxygen, the only drawback is that it would be a "separate" API documentation, with a different template after clicking on "C/C++ API".
Breathe is supposed to link doxygen and sphinx nicely but it looks like it cannot reproduce the hierarchy graphs produced from doxygen.

[tridelat]

@cekees for 3) the mathematical formulas actually seem to render, for example here: https://tridelat.github.io/proteus/capi/classDensityRelation.html#exhale-class-classdensityrelation
For the hierarchy/dot graphs, I don't think it is possible with breathe (yet at least), see breathe-doc/breathe#45
We can point directly to the doxygen html pages instead of using breathe if we want to inlcude the C++ graphs. It would look similar to the current https://proteustoolkit.org/capi/html/hierarchy.html (with no link back to https://proteustoolkit.org/)