Setup online API documentation about aikido

[cdellin]

FWIW for my LEMUR docs (C++ using Doxygen), I found a way to get them built by Read the Docs, even though they technically only support Sphinx. RtD has Doxygen installed on their build servers (to support projects using Breathe). It works because Sphinx is configured by a conf.py script, which is just import-ed by Sphinx during the build process, so you can add whatever code you want to it to do arbitrary things. In my case, I just generate an empty contents.rst (so Sphinx generates nothing), then shell out to call Doxygen on the project, making sure to put the output html where RtD expects the generated docs to be.

The LEMUR docs are a bit complicated, because I split it into multiple separate Doxygen projects (for ROS compatibility), so my conf.py file file is a bit complicated (it post-processes the generated html documentation to add html headers and footers linking together the different packages). If you just want to run Doxygen on a single project, it would be much shorter (mostly just a subprocess.call('doxygen')). I think Read the Docs supports building docs for different branches, and of course does auto-building on each commit.

[psigen]

We should pick an option that still lets us build HTML documentation directly from the repository if we want to, both for flexibility of hosting and to make it sane to author the docs.

• gh-pages more or less hosts any static HTML, so that should work with any doc generator.
• CodeDocs and ReadTheDocs both have slightly specialized build systems that kind of lock us into particular doc systems (Doxygen and Sphinx + Breathe, respectively). This is fine as long as we know what we are getting into, and we can still build the same docs locally.
• ReadTheDocs is nice in that its underlying hosting mechanism is open-source, as well as its theme. It does support building per-branch out of the box.
• ReadTheDocs occasionally has really slow servers. CodeDocs might as well. Since we are operating on the free tier, we are getting bargain basement hosting here. I would expect that Github or any static hosting provider will handily outperform these services in uptime and load-times, which significantly reduces frustration when knee-deep in API docs.
• @jslee02: how does search work on the static gh-pages? Does it exist? Is it handled client-side?
• It is highly likely we will need a few customizations to handle the complex combination of C++, Python, and autogenerated C++/Python bindings that we are building. We need to make sure they are supported by the online builders.

Before we commit to any online API, I think we should try to build the docs locally with Sphinx + Breathe and Doxygen and see how we like their respective layouts. Most online builders are just going to use some variant of these two systems AFAIK. Let's not jump ahead and then get tied into some online framework and be unable to build/mirror our own docs.

[cdellin]

Certainly +1 for what @psigen said. For LEMUR I have a Makefile so I can just cd into the docs directory and type make to generate the docs locally, and it's essential.

[jslee02]

@psigen's suggestion: #245 (comment)

I would highly recommend using a doc generator that can be run locally to produce static HTML, then use manual or conventional CI processes to put the static HTML artifact on a web server of your choosing. GitHub Pages works really well for this, and is also an intuitive place for people to look for documentation.

This gives us the most flexibility (if we decide to change generators), reliability (we can manually build, upload, backup, and correct issues if needed), and customizability (we can control which documentation gets built).

[brianhou]

I'm in favor of just putting what we have online now. #319 cleans up the Doxygen results so that it doesn't include paths from all over your local filesystem, so I'm now somewhat satisfied by its output.

How does search work on the static gh-pages? Does it exist? Is it handled client-side?

I think if we use GitHub Pages (and probably these other options, if they just produce static HTML/CSS/JS) we can only do client-side search. Doxygen supports client-side search, although it's quite slow (from personal experience with the DART docs). I don't think it's worth the effort to figure out how to optimize this now, but it's definitely going to be a bit annoying.

The next step is to hook things up in CI. In the meantime, I think we can manually push versions to gh-pages starting with 0.3.0.

[jslee02]

I believe this is resolved by #331

[brianhou]

Not completely -- we still need to figure out how to deploy different versions. We can create a new issue to track that though.

[jslee02]

👍 for creating a new issue for that.