diff --git a/doc/APIreference.rst b/doc/APIreference/APIdatastructures.rst similarity index 95% rename from doc/APIreference.rst rename to doc/APIreference/APIdatastructures.rst index 05f535c8..847c6bfe 100644 --- a/doc/APIreference.rst +++ b/doc/APIreference/APIdatastructures.rst @@ -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 `_ 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 ` 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`. diff --git a/doc/APIreference/APIfunctions.rst b/doc/APIreference/APIfunctions.rst new file mode 100644 index 00000000..05ff7804 --- /dev/null +++ b/doc/APIreference/APIfunctions.rst @@ -0,0 +1,94 @@ +.. _API: + +========= +Functions +========= + +The main header `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 ` 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`. diff --git a/doc/functions.rst b/doc/APIreference/functions.rst similarity index 100% rename from doc/functions.rst rename to doc/APIreference/functions.rst diff --git a/doc/functions_override.rst b/doc/APIreference/functions_override.rst similarity index 100% rename from doc/functions_override.rst rename to doc/APIreference/functions_override.rst diff --git a/doc/APIreference/index.rst b/doc/APIreference/index.rst new file mode 100644 index 00000000..9184220c --- /dev/null +++ b/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 diff --git a/doc/conf.py b/doc/conf.py index 284f4918..6d91b5a3 100644 --- a/doc/conf.py +++ b/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', - 'functions_override.rst', 'XMLschema.rst' + '_build', 'Thumbs.db', '.DS_Store', 'includes/*', 'APIreference/functions.rst', + 'APIreference/functions_override.rst', 'XMLschema.rst' ] redirects = { diff --git a/doc/ext/mujoco_include.py b/doc/ext/mujoco_include.py index ab62fb6e..ea9d2b1c 100644 --- a/doc/ext/mujoco_include.py +++ b/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}' diff --git a/doc/index.rst b/doc/index.rst index b72827de..2e4d3975 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,7 +13,7 @@ XMLreference programming/index.rst models - APIreference + APIreference/index.rst python unity changelog diff --git a/doc/programming/index.rst b/doc/programming/index.rst index e86113aa..590f769d 100644 --- a/doc/programming/index.rst +++ b/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. -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 \ No newline at end of file + visualization