(Update / Improve) A Developer guide

[kellertuer]

in @Affie said in JuliaManifolds/LieGroups.jl#5

Perhaps it will help to develop a developer guide over time with steps that has to be checked off with details such as: run the formatter, put tests here, add docstrings like this, add these traits.

I will check what needs to be done, but to first document the state “as is”:
We have

• a page about the design ideas https://juliamanifolds.github.io/ManifoldsBase.jl/stable/design/ especially explaining the usual order of variables, 3 levels we work on (to avoid ambiguities) and the mutating/allocating ideas.
• a Paige about the decorator idea and the current trait system https://juliamanifolds.github.io/ManifoldsBase.jl/stable/decorator/ – that I was a large fan of to get started with, but it turns out to be not so user friendly, neither to the developer nor to someone using it because the error messages are sometimes bit weird. I would love to have a better system here, but maybe a very technical, complicated wish (due to performance)
• We have the https://juliamanifolds.github.io/Manifolds.jl/stable/misc/CONTRIBUTING.html (a rendered version of https://github.com/JuliaManifolds/Manifolds.jl/blob/master/CONTRIBUTING.md mentioning for example code style.

So at first glance I can spot two things we missed to update, probably in the last file

• any change should be documented in the https://github.com/JuliaManifolds/Manifolds.jl/blob/master/NEWS.md – and since we ourselves forgot about that often (and with we I also specifically mean me) we have a test to fail when this file is not changed on a PR
• doc strings, and what they should contain

Let me know what else we a re missing and I will do a PR working on / improving these here; I will check afterwards wherelse this should then be adapted (ManifoldsBase/Manopt/LieGroups/...)

[Affie]

I haven't seen all the pages you linked before, only https://juliamanifolds.github.io/Manifolds.jl/stable/misc/CONTRIBUTING.html
The paragraphs bellow this just helped me quite a bit when I read it now.

I used https://juliamanifolds.github.io/ManifoldsBase.jl/stable/tutorials/implement-a-manifold/ before to create our own group but just ended up changing the article functions slightly to use manifolds.jl ones. I now know roughly that I should have decorated some manifold with a group, done something with get_coordinates and get_vector to get hat and vee, maybe define exp_lie, log_lie, adjoint, etc., done something with Cartan-Schouten-connections to get the exp I want, etc.

I would say what is missing is the step-by-step list so you find everything that you need to know about.
Mabye a good analogy is the julia docs on interfaces

[kellertuer]

Thanks for your feedback!
You can work without a decorator for sure, you just gain a few things automatically if you work with a decorator (yes you also gain automatically more complicated error messages).

The “problem” with the tutorial you used is, that it is (plain) manifold centred, so it does not cover decorators. But a new tutorial in LieGroups (where LieGroups are also not modelled as decorators) is planned there for sure.

I will check your link and think about how to best improve our docs pages then, also taking into account your other remarks.

[kellertuer]

Oh, I noch clicked on your “Julia docs on Interfaces” – and that is the ManifoldsBase docs? So which Julia docs do you refer to?

[Affie]

Sorry, https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-iteration

[kellertuer]

see, our interface is all full doc strings; so maybe we could add a small overview upfront.

[Affie]

Don't get me wrong, I find the documentation very good. There is just a lot when you look at contributing some functionality or manifold.

[kellertuer]

Thanks for the comment, much appreciated – and no worries, I did not understand/see your comments as generically saying the docs are bad.

Then, as the summary I already pointed out, maybe a bit of a guide where to find stuff could be added in a few places.