Split API reference pages into Data Structures and Functions pages.

PiperOrigin-RevId: 510422950
Change-Id: I6b2eebab0c0020b80fec83094aa65c6a412e277e

doc/APIreference/APIdatastructures.rst

@@ -1,12 +1,6 @@
-=============
+===============
-API Reference
+Data Structures
-=============
+===============
-
-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.
 
 .. _Type:
 
@@ -1450,96 +1444,3 @@ Numeric constants
 |                  |        | but for the compiled library.                                                          |
 +------------------+--------+----------------------------------------------------------------------------------------+
 
-.. _API:
-
-API functions
--------------
-
-The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large
-number of functions. However the functions that most users are likely to need are a small fraction. For example,
-:ref:`simulate.cc <saSimulate>` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these
-functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This
-includes us as users of MuJoCo -- we do our own work with the public library instead of relying on internal builds.
-
-.. include:: functions.rst
-
-.. _Macros:
-
-Macros
-^^^^^^
-
-.. _mjMARKSTACK:
-
-mjMARKSTACK
-~~~~~~~~~~~
-
-.. code-block:: C
-
-   #define mjMARKSTACK int _mark = d->pstack;
-
-This macro is helpful when using the MuJoCo stack in custom computations. It works together with the next macro and the
-:ref:`mj_stackAlloc` function, and assumes that mjData\* d is defined. The use pattern is this:
-
-::
-
-       mjMARKSTACK
-       mjtNum* temp = mj_stackAlloc(d, 100);
-       // ... use temp as needed
-       mjFREESTACK
-
-.. _mjFREESTACK:
-
-mjFREESTACK
-~~~~~~~~~~~
-
-.. code-block:: C
-
-   #define mjFREESTACK d->pstack = _mark;
-
-Reset the MuJoCo stack pointer to the variable \_mark, normally saved by mjMARKSTACK.
-
-.. _mjDISABLED:
-
-mjDISABLED
-~~~~~~~~~~
-
-.. code-block:: C
-
-   #define mjDISABLED(x) (m->opt.disableflags & (x))
-
-Check if a given standard feature has been disabled via the physics options, assuming mjModel\* m is defined. x is of
-type :ref:`mjtDisableBit`.
-
-.. _mjENABLED:
-
-mjENABLED
-~~~~~~~~~
-
-.. code-block:: C
-
-   #define mjENABLED(x) (m->opt.enableflags & (x))
-
-Check if a given optional feature has been enabled via the physics options, assuming mjModel\* m is defined. x is of
-type :ref:`mjtEnableBit`.
-
-.. _mjMAX:
-
-mjMAX
-~~~~~
-
-.. code-block:: C
-
-   #define mjMAX(a,b) (((a) > (b)) ? (a) : (b))
-
-Return maximum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_max`.
-
-.. _mjMIN:
-
-mjMIN
-~~~~~
-
-.. code-block:: C
-
-   #define mjMIN(a,b) (((a) < (b)) ? (a) : (b))
-
-Return minimum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_min`.

doc/APIreference/APIfunctions.rst

@@ -0,0 +1,94 @@
+.. _API:
+
+=========
+Functions
+=========
+
+The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large
+number of functions. However the functions that most users are likely to need are a small fraction. For example,
+:ref:`simulate.cc <saSimulate>` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these
+functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This
+includes us as users of MuJoCo -- we do our own work with the public library instead of relying on internal builds.
+
+.. include:: functions.rst
+
+.. _Macros:
+
+Macros
+^^^^^^
+
+.. _mjMARKSTACK:
+
+mjMARKSTACK
+~~~~~~~~~~~
+
+.. code-block:: C
+
+   #define mjMARKSTACK int _mark = d->pstack;
+
+This macro is helpful when using the MuJoCo stack in custom computations. It works together with the next macro and the
+:ref:`mj_stackAlloc` function, and assumes that mjData\* d is defined. The use pattern is this:
+
+::
+
+       mjMARKSTACK
+       mjtNum* temp = mj_stackAlloc(d, 100);
+       // ... use temp as needed
+       mjFREESTACK
+
+.. _mjFREESTACK:
+
+mjFREESTACK
+~~~~~~~~~~~
+
+.. code-block:: C
+
+   #define mjFREESTACK d->pstack = _mark;
+
+Reset the MuJoCo stack pointer to the variable \_mark, normally saved by mjMARKSTACK.
+
+.. _mjDISABLED:
+
+mjDISABLED
+~~~~~~~~~~
+
+.. code-block:: C
+
+   #define mjDISABLED(x) (m->opt.disableflags & (x))
+
+Check if a given standard feature has been disabled via the physics options, assuming mjModel\* m is defined. x is of
+type :ref:`mjtDisableBit`.
+
+.. _mjENABLED:
+
+mjENABLED
+~~~~~~~~~
+
+.. code-block:: C
+
+   #define mjENABLED(x) (m->opt.enableflags & (x))
+
+Check if a given optional feature has been enabled via the physics options, assuming mjModel\* m is defined. x is of
+type :ref:`mjtEnableBit`.
+
+.. _mjMAX:
+
+mjMAX
+~~~~~
+
+.. code-block:: C
+
+   #define mjMAX(a,b) (((a) > (b)) ? (a) : (b))
+
+Return maximum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_max`.
+
+.. _mjMIN:
+
+mjMIN
+~~~~~
+
+.. code-block:: C
+
+   #define mjMIN(a,b) (((a) < (b)) ? (a) : (b))
+
+Return minimum value. To avoid repeated evaluation with mjtNum types, use the function :ref:`mju_min`.

doc/APIreference/index.rst

@@ -0,0 +1,14 @@
+.. _APIreference:
+
+=============
+API Reference
+=============
+
+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.
+
+.. toctree::
+   :maxdepth: 2
+
+   APIdatastructures
+   APIfunctions

doc/conf.py

@@ -57,8 +57,8 @@ templates_path = ['templates']
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    '_build', 'Thumbs.db', '.DS_Store', 'includes/*', 'functions.rst',
+    '_build', 'Thumbs.db', '.DS_Store', 'includes/*', 'APIreference/functions.rst',
-    'functions_override.rst', 'XMLschema.rst'
+    'APIreference/functions_override.rst', 'XMLschema.rst'
 ]
 
 redirects = {

doc/ext/mujoco_include.py

@@ -40,7 +40,7 @@ class MujocoInclude(LiteralInclude):
       end_line = source.end
 
     # Config arguments and options for LiteralInclude.
-    self.arguments[0] = _FILENAME
+    self.arguments[0] = f'../{_FILENAME}'
     self.options['language'] = 'C'
     self.options['lines'] = f'{start_line}-{end_line}'
 

doc/index.rst

@@ -13,7 +13,7 @@
    XMLreference
    programming/index.rst
    models
-   APIreference
+   APIreference/index.rst
    python
    unity
    changelog

doc/programming/index.rst

@@ -7,10 +7,10 @@ Programming
 Introduction
 ~~~~~~~~~~~~
 
-This chapter is the MuJoCo programming guide. A separate chapter contains the :doc:`../APIreference` documentation.
+This chapter is the MuJoCo programming guide. A separate chapter contains the :doc:`../APIreference/index`
-MuJoCo is a dynamic library compatible with Windows, Linux and macOS, which requires a process with AVX instructions.
+documentation. MuJoCo is a dynamic library compatible with Windows, Linux and macOS, which requires a process with AVX
-The library exposes the full functionality of the simulator through a compiler-independent shared-memory C API. It can
+instructions. The library exposes the full functionality of the simulator through a compiler-independent shared-memory C
-also be used in C++ programs.
+API. It can also be used in C++ programs.
 
 The MuJoCo codebase is organized into subdirectories corresponding to different major areas of functionality: