Document the order of the elements in the tangent space, in a prominent place

[joansola]

An important detail in the usage of manif is the meaning of the Jacobians. In particular, the order of the different elements in the tangent vector is crucial.

For example, in SE(3) we may have [theta,p] or [p,theta]. Mathematically, this is irrelevant. But code-wise, the order matters.

In SGal(3) there are 4 elements, so the number of options is huge, and only one is valid, It happens that the selected order (rho, nu, theta, t) does not match the order in the constructor of SGal3 (p, q, v, t), leading to possible confusion. The only good solution is a good documentation.

The arbitrary choice of these orderings should be clearly documented in a prominent place (e.g. in the GroupTangent classes), and appear in the documentation pages generated by doxygen.

I also noticed a few Error404 when browsing the doxygen documentation, especially when looking for specific files in the SGal3 class impl folders.

[artivis]

Hi @joansola ,
Thanks for pointing that out. The SGal(3) constructor inputs order mismatch is really unfortunate ...
Regarding the doc, I've been planning on revamping it entirely for a while now. The current setup is clunky and annoying to work with. I just need to find the time/motivation to do so...

[joansola]

I can help writing doc, if you just tell me where :-)

[joansola]

I suggest adding a table in the doc frontpage with all relevant details for each supported group, and augment it as we introduce more groups. This way it can be done before you find a neat way to organize the documentation process/tools

[joansola]

For example:

group	group parts	tangent parts, in order
Rn	v	v
SO(3)	R	theta
SE(3)	R,p	p,theta
SGal(3)	R v p t	rho, nu, theta, s

etc

[artivis]

Hi @joansola,

I started re-working the documentation from scratch (see #324), it is still in progress. In the meantime you can give it a look locally simply running cd docs && make run. You'll need to install at least doxygen (maybe more?). The new doc website should then be served locally.

If you wanna start working on this table, I'd suggest you branch off of fix/docs and create a new page in docs/explanation/. To link it, simply add the file name in the toc directive in docs/exaplanation/index.md.

[joansola]

OK I got it to compile.

On the Firefox side, navigation is not good: clicking on links produces a folder view of the contents of the link. On that folder, you need to click on 'index.html' to actually get to the desired page.

I'll find some time to work on the actual doc next week.

Thanks!

[artivis]

Thanks for the feedback.
However it works fine for me on both firefox & chrome. Let us look at that once I'm done with the on-going migration.

[joansola]

I am seeing a lot of errors while compiling the doc. Is this normal?

output.log

[artivis]

Yeah at the moment it is expected, but the doc website should still build.

[joansola]

Thanks for the feedback. However it works fine for me on both firefox & chrome. Let us look at that once I'm done with the on-going migration.

In my case (macos) I have tried Firefox and Safari and both fail to work in the same way: clicking on links opens the respective folder, not the index.html file.

I have observed that the link is actually the folder containing the index.html file, without the file, for example file:///Users/jsola/dev/manif/docs/_build/tutorial/. Should these links contain the full path including the index.html file? Just wondering...

[artivis]

No idea what's going on on your side.
Just in case, you can download the doc (doc artifact) from the a CI documentation job (e.g. here) and serve it locally by running e.g. python3 -m http.server --bind 127.0.0.1 8000 in the _build folder.

[joansola]

Hey @artivis I created another PR for the doc, I did not see this one until today. The other PR is #325 . Do you want to cleanup my mess?

[artivis]

I've merged your branch in mine. I'll check what's going on with the CI on my pr asap and merge it as I'm done with the migration.