Interface Documentation rewrite

[kellertuer]

This is the companion PR to JuliaManifolds/ManifoldsBase.jl#69 to rewrite the interface documentation.

This first sketch has the one problem that a lot of functions are doubled, but we would have to do separate files for

• Manifold/MPoint/TVector/CoTVector (maybe together with the next)
• all exp/logs
• all retraction related stuff
• all projection related stuff
• maybe also a file just for all remaining interface functions

to not state all functions explicitly (like it is now done partly). But I would like to have some feedback on the structure of the Manifold functions section first, before I continue with that (and the graphics and such).

[Affie]

This is great, thanks! It would have saved us hours...
cc @dehann

[kellertuer]

thanks for the feedback – and sorry that it took you longer.
While we try to document as much as possible (see also all the formulae at the manifolds themselves) it is sometimes hard to have the right level of detail in mind – so your feedback is valuable here and we then of course try to adapt the docs.

[kellertuer]

Since I am rearranging anyways; I am not yet sure how the ManifoldTestsubpackage is intended to work. I expected the test functions to be included there, but they are not. What is the reason for this? That way the test functions are included in the main scope on Manifolds (since tests is loaded and those are included in this case). With being in the main scope, they are warning for being undocumented.

Shoul we maybe include the test functions into the Subpackage and only do a using ManifoldTest when test is loaded?

[mateuszbaran]

I think the intention was to avoid adding a new module through Requires.jl but I don't really know if that's necessary.

[kellertuer]

We could keep it as a submodule, but the way it is currently included we can just keep the includes and omit the submodule :)

[mateuszbaran]

Hm, that's probably due to those exports? Anyway, feel free to change that if you don't like it 🙂 .

[kellertuer]

I think I already have an idea.

[kellertuer]

Finished the idea and locally (together with the ManifoldsBase PR) the docs run fine and there is no documentation missing; all tests also still run fine.

[kellertuer]

I added two figures, one for the projection one for the retraction

https://github.com/JuliaManifolds/Manifolds.jl/blob/7dd0ce6342f9c17af78ce1e4e3ae33515fcfc449/docs/src/assets/images/projection_illustration_600.png

https://github.com/JuliaManifolds/Manifolds.jl/blob/7dd0ce6342f9c17af78ce1e4e3ae33515fcfc449/docs/src/assets/images/retraction_illustration_600.png

They stem from using Manifolds with PGFPLotsX; the only thing I am not yet 100% sure about: The colours are currently chosen to fit both light and dark mode (Paul Tol's colours, but also his gray for the text), which I think is not the best choice for text but I have not much more of an idea.

[Affie]

About the project illustration.

Is s2 correct?

Should it not be this one: project(M::AbstractManifold, p, X) and be from the ambient space representation of a vector X?

[kellertuer]

Thanks for the question.
The s2 including its whole label is correct. Maybe the name q is irritating here.
For s1 the q acts as a point on the manifold R^2 (the embedding) and we project onto the circle.
For s2 the q acts as a vector in the embedding that gets projected onto the tangent plane. So in this case q is said X in the function project(M,p,X).

[kellertuer]

This is now updated and just has to wait for the ManifoldsBase branch.

[codecov]

Codecov Report

Merging #359 (14030aa) into master (eb296b5) will decrease coverage by 0.00%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master     #359      +/-   ##
==========================================
- Coverage   97.92%   97.92%   -0.01%     
==========================================
  Files          78       76       -2     
  Lines        5917     5915       -2     
==========================================
- Hits         5794     5792       -2     
  Misses        123      123              

Impacted Files	Coverage Δ
src/Manifolds.jl	100.00% <ø> (ø)
src/manifolds/MetricManifold.jl	98.32% <ø> (ø)
src/manifolds/SkewHermitian.jl	100.00% <ø> (ø)
src/nlsolve.jl	100.00% <100.00%> (ø)
src/tests/tests_forwarddiff.jl	100.00% <100.00%> (ø)
src/tests/tests_general.jl	95.98% <100.00%> (+0.03%)	⬆️
src/tests/tests_group.jl	94.37% <100.00%> (ø)
src/tests/tests_reversediff.jl	100.00% <100.00%> (ø)

---

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 eb296b5...14030aa. Read the comment docs.

[kellertuer]

I am not sure why documenter is failing here, I updated the Project.toml but it seems to be fixed to not be above 0.11.1 somehow (and should be 0.11.3) and hence fails. But there is no occurrence of 0.11.1 in the project, so I don't know why it fails.

Manifolds seems to also be stuck there to 0.4.x which seems to be the problem, but it is nowhere restricted to that, so I am confused why it is not upgraded to 0.5 In the docs environment...

[mateuszbaran]

The currently failing documenter job picks Manifolds.jl 0.5.0 but the ManifoldsBase.jl version is indeed 0.11.1 and 0.11.3 isn't visible. I've noticed before that it takes some time (even more than a day) before documenter jobs see a newly registered version of a package.

[kellertuer]

Thanks for the help. I can reproduce it here locally activating the docs environment, so we might have to just wait (and it is either ManifoldsBase or even Manifolds, I am not 100% sure.

[mateuszbaran]

I think this looks very nice now 👍 .