Fix API class documentation

[jgillick]

Fixes:

• 3.7 API Reference Documentation broken? #78
• [Bug]: API docs for Entity classes are empty Genesis#2186

Genesis version 0.3.5 stopped allowing classes to be imported before Genesis initialization. This lead autodoc to fail with the exception: Genesis hasn't been initialized. Did you call gs.init(). The quick fix is to initialize GS at the top of the conf.py`.

In the future, this might fail if support for the CPU backend is dropped, because I'm not sure readthedocs servers have appropriate GPUs. At that point, the documentation system might need to move to static analysis with sphinx-autodoc2.

[duburcqa]

To be clear, CPU backend is extremely unlikely to be dropped. It is essential for non-batched rigid body simulation.

[duburcqa]

But why not moving to sphinx-autodoc2 as you suggest straight away?

I'm not a fan of initializing Genesis because it forces a single data type where it should be dynamic (depending on precision and whether or not performance mode is enabled) but I don't see any obvious solution to this issue. Static analysis is not going to help either. The only solution I can think of is adding some higher-level Tensor encapsulation to abstract the actual runtime type, and similar for dtype.

[jgillick]

Going to sphinx-autodoc2 straight away would take more work, as (I believe) it expects the source code to be local. To support this, we'd need to move the .readthedocs.yaml file up to the Genesis repo, but we should still be able to keep docs as a git submodule. This move is likely a good idea anyway, because currently ReadTheDocs isn't notified when the main repo published a new version, and so it doesn't automatically update the API docs.

I'll attempt this move in a PR soon.

[jgillick]

After digging into sphinx-autodoc2, it looks like it hasn't been updated in over 2 years, so I'd consider it an abandoned project. Despite this, I was able to get it documenting most of the APIs, however, it lacks many of the options of autodoc, and some of the styling got messy. So, I recommend continuing to use autodoc as long as it works.

[duburcqa]

So, I recommend continuing to use autodoc as long as it works.

I see. This plan sounds good to me. Thank you for digging into sphinx-autodoc2!