New GTSAM ReadTheDocs documentation

[jlblancoc]

This is a follow up of #466
cc: @dellaert , @ayushya19, @pks-97 , @edwardwterry

I reorganized all the work done so far into a clean commit ( 900376f ), based on a new branch rtd-docs, on which new development should take place: pull requests should go against that branch, and starting up should be done by cloning this git repo and switching to the rtd-docs branch.

Design of docs

• Based on standard sphinx + rtd template + a customized "hack" to run Doxygen inside conf.py and allow browsing Doxygen documentation for all C++ classes.
• RST hand-written pages are under /docs
• I guess all docs under /doc (NOTE: Old=/doc, New=/docs) should be removed and ported to Rest pages under /docs
• Doxygen docs: a lot of work is required to clean it up, e.g. organize all classes into groups, etc. (JL: This was my observation back in 2020... is it still right, @varunagrawal ?)

Test web docs locally

1. Clone this repo and switch to the rtd-docs branch.
2. Run:

cd docs
python3 -m pip install -r requirements.txt   # Only once! You can also build a venv if preferred
make html
xdg-open build/html/index.html

(JL: Maybe you have missing dependencies? comment below...)

Pending tasks

• Someone has already taken the "gtsam" project name in ReadTheDocs. Anyone of you around? If yes, please DM me ( jlblanco@ual.es ). If nobody shows up, I could ask RTD admins if it's possible to claim the domain. In the meanwhile, the public URL is: https://gtsam-jlblanco-docs.readthedocs.io/
• All docs under /doc should be removed and ported to Rest pages under /docs
• Currently half-ported RST docs should be reviewed and their formatting, images, etc. fixed as in their original versions.

What work can be distributed by volunteers:

Please, @ayushya19, @pks-97 , @edwardwterry, and whoever wants to give a hand:

1. Follow the instructions above for "Test web docs locally" to make sure you can replicate the web structure on your local machines.
2. Browse through the (few) existing page, take note of what's clearly wrong with formatting, images, etc. Compare it with the current web: https://gtsam.org/
3. Doxygen docs themselves are visible here. Feel free of also checking them and proposing improvements in any way.
4. Comment here what page(s) are you willing to work in (e.g. "building", "installing", etc.) so each page is being worked by only one person. Create a fork of this repo and (starting at the rtd-docs branch), start your contributions! Once done and happy with the results, make a commit and open a PR against the "rtd-docs" branch of this repo.

[dellaert]

Thanks for getting this started @jlblancoc !!

• I checked in my email and don't see correspondence from readthedocs.io, but it might have been @matthewsklar or another collaborator back in the day. Asking the admins would be great.
• When making html (on Mac) I get

Extension error:
Could not import extension sphinx_rtd_theme (exception: No module named 'sphinx_rtd_theme')
make: *** [html] Error 2

[jlblancoc]

@ dellaert

• When making html (on Mac) I get

Extension error:
Could not import extension sphinx_rtd_theme (exception: No module named 'sphinx_rtd_theme')
make: *** [html] Error 2

Ok, I added the docs build dependencies here, install them as usual (I also updated the instructions at the top of this discussion).

[ayushya19]

I can get started with it.

[ayushya19]

I can pick up installing.

[ayushya19]

Observations from the page.

1. The Installing page has no content.

2. has installation steps written over them.

3. The formatting seems normal, probably because there is no content.

I will try to fill up this page and raise a pr.

[jlblancoc]

Cool! Let us know how it goes...

[ayushya19]

Sure! @jlblancoc , I was able to update the "Installing" and "Importing GTSAM in your projects" section.

I will be raising a pr soon for this.

However, I am not able to find the right source for "Write your first GTSAM program" sub section. Any Pointers?

I tried looking at the website,the doxygen docs, and the github. :/

[ayushya19]

PR raised.

[edwardwterry]

Thanks for setting this up. I will claim checking for missing figures and fixing broken links and references in the Tutorials section.

[dellaert]

Thanks!
pip install sphyx sphinx_rtd_theme solved it !
Some questions about the generated doxygen:

• It looks very doxygen and not very RTD :-) Can we more tightly integrate it?
• it says 4.0.2 at the top. Where is version specified?
• does anyone know the right way to do groups? Somehow SFM is the only one to get a string and it is wrong
• same for classes: almost none have a docstring showing up in the "groups"

[jlblancoc]

It looks very doxygen and not very RTD :-) Can we more tightly integrate it?

Yeap... that's because the current scripts are actually building the Sphinx (.rst or .md pages, which end up with the "RTD like and feel"), and separately, the good-old Doxygen pure HTML pages, and there's no logical connection between them.

There is a way to do such connection, using the doxyrest project.
The process is complex... but I successfully set it up for mrpt (example of the result).
We will need a new Makefile here quite similar to this stack of hacks ;-)

I'll try to import that method to gtsam too asap. In the meanwhile, work on Sphinx pages (both .rst and .md are supported) and doxygen (grouping, etc.) can go on without problems. doxyrest basically changes the appearance of Doxygen pages.

it says 4.0.2 at the top. Where is version specified?

Look here

does anyone know the right way to do groups? Somehow SFM is the only one to get a string and it is wrong

Shameless self-citation :-)