Split API reference pages into Data Structures and Functions pages.

PiperOrigin-RevId: 510422950 Change-Id: I6b2eebab0c0020b80fec83094aa65c6a412e277e
2023-02-17 07:05:32 -08:00
parent 2607e67f8d
commit 090c25988a
9 changed files with 120 additions and 111 deletions
@@ -1,12 +1,6 @@
-=============
-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.
+===============
+Data Structures
+===============

 .. _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`.
@@ -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`.
@@ -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
@@ -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',
-    'functions_override.rst', 'XMLschema.rst'
+    '_build', 'Thumbs.db', '.DS_Store', 'includes/*', 'APIreference/functions.rst',
+    'APIreference/functions_override.rst', 'XMLschema.rst'
 ]

 redirects = {
@@ -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}'

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

-This chapter is the MuJoCo programming guide. A separate chapter contains the :doc:`../APIreference` documentation.
-MuJoCo is a dynamic library compatible with Windows, Linux and macOS, which requires a process with AVX instructions.
-The library exposes the full functionality of the simulator through a compiler-independent shared-memory C API. It can
-also be used in C++ programs.
+This chapter is the MuJoCo programming guide. A separate chapter contains the :doc:`../APIreference/index`
+documentation. MuJoCo is a dynamic library compatible with Windows, Linux and macOS, which requires a process with AVX
+instructions. The library exposes the full functionality of the simulator through a compiler-independent shared-memory C
+API. It can also be used in C++ programs.

 The MuJoCo codebase is organized into subdirectories corresponding to different major areas of functionality:

@@ -261,4 +261,4 @@ now lazily resolved at runtime after the switch to GLAD, the "nogl" libraries ar

    samples
    simulation
-    visualization
+    visualization