mujoco
mujoco copied to clipboard
google-deepmind
Automatically generate the API reference
The API reference (doc/APIreference.rst) is currently written by hand. This means it immediately goes out of date with any changes to the API.
We need a solution for auto-generating the API reference that satisfies the following requirements:
- It is complete: either every function is automatically included, or we get a build error if anything is missing.
- Code snippets defining structs should automatically be included.
- Function signatures are automatically included (either as a code snippet, or in a different standard form).
- We have control of the ordering and grouping of functions / data types.
- We can write extra bits of reStructuredText around the automatically generated functions (e.g the blurbs about "primitive types" or "physics callbacks").
One possible approach would be to use an RST file as a template, which will get filled in automatically. i.e, have a template file like:
=============
API Reference
=============
Introduction
------------
This chapter is the reference manual for MuJoCo. It is generated from the header files included with MuJoCo, but also
contains additional text not available in the headers.
...
ENUM(mjtDisableBit, mjmodel.h)
Constants which are powers of 2. They are used as bitmasks for the field ``disableflags`` of :ref:`mjOption`.
At runtime this field is ``m->opt.disableflags``. The number of these constants is given by ``mjNDISABLE`` which is
also the length of the global string array :ref:`mjDISABLESTRING` with text descriptions of these flags.
...
FUNCTION_TYPE(mjfGeneric, mjdata.h)
This is the function type of the callbacks :ref:`mjcb_passive` and :ref:`mjcb_control`.
...
etc.
We can then have a tool that check that all public declaration in the headers have a corresponding entry in the docs template.
As far as I can tell, mujoco is written in C/C++, right? It seems you could read the documentation from the source with doxygen and then bridge it into sphinx via breathe (https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/). What would give you the ability to generate modern documentation directly from source.
