Formatting improvements to docs Overview chapter.

PiperOrigin-RevId: 561586361
Change-Id: Ib529cbd49cebf26d802d023d12d973491e41d3ad

doc/changelog.rst

@@ -38,11 +38,11 @@ General
    Euler integrator. See the :ref:`Numerical Integration<geIntegration>` section for more details.
 #. Added the flag :ref:`invdiscrete<option-flag-invdiscrete>`, which enables discrete-time inverse dynamics for all
    :ref:`integrators<option-integrator>` other than ``RK4``. See the flag documentation for more details.
-#. Changed the function ``mj_stackAlloc`` to allocate an arbitrary number of bytes, rather than in multiples of
+#. Changed the function :ref:`mj_stackAlloc` to allocate an arbitrary number of bytes, rather than in multiples of
    ``sizeof(mjtNum)``, and add an additional argument for specifying the alignment of the returned pointer. The existing
-   functionality of allocating ``mjtNum`` arrays is still available through the new function ``mj_stackAllocNum``.
+   functionality of allocating ``mjtNum`` arrays is still available through the new function :ref:`mj_stackAllocNum`.
-#. Renamed the ``nstack`` field in ``mjModel`` and ``mjData`` to ``narena``. Changed ``narena``, ``pstack``, and
+#. Renamed the ``nstack`` field in :ref:`mjModel` and :ref:`mjData` to ``narena``. Changed ``narena``, ``pstack``, and
-   ``maxuse_stack`` to count number of bytes rather than number of ``mjtNum``s.
+   ``maxuse_stack`` to count number of bytes rather than number of :ref:`mjtNum` |-| s.
 
 Python bindings
 ^^^^^^^^^^^^^^^

doc/overview.rst

@@ -239,8 +239,7 @@ The function :ref:`mj_step` is the top-level function which advances the simulat
 of course is just a passive dynamical system. Things get more interesting when the user specifies controls or applies
 forces and starts interacting with the system.
 
-Next we provide a more elaborate example illustrating several features of MJCF.
+Next we provide a more elaborate example illustrating several features of MJCF. Consider the following
-
 `example.xml <_static/example.xml>`__:
 
 .. code:: xml
@@ -332,15 +331,21 @@ XML file, default values are used. The options are designed such that the user c
 simulation time step. Within a time step however none of the options should be changed.
 
 ``mjOption``
+^^^^^^^^^^^^
+
 This structure contains all options that affect the physics simulation. It is used to select algorithms and set their
 parameters, enable and disable different portions of the simulation pipeline, and adjust system-level physical
 properties such as gravity.
 
 ``mjVisual``
+^^^^^^^^^^^^
+
 This structure contains all visualization options. There are additional OpenGL rendering options, but these are
 session-dependent and are not part of the model.
 
 ``mjStatistic``
+^^^^^^^^^^^^^^^
+
 This structure contains statistics about the model which are computed by the compiler: average body mass, spatial
 extent of the model etc. It is included for information purposes, and also because the visualizer uses it for
 automatic scaling.
@@ -357,6 +362,8 @@ purpose of including an asset is to reference it, and referencing can only be do
 undefined.
 
 Mesh
+^^^^
+
 MuJoCo can load triangulated meshes from OBJ files and binary STL. Software such as `MeshLab
 <https://www.meshlab.net/>`__ can be used to convert from other formats. While any collection of triangles can be
 loaded and visualized as a mesh, the collision detector works with the convex hull. There are compile-time options
@@ -367,6 +374,8 @@ Mesh
 custom binary file format for normals and texture coordinates. Meshes can also be embedded directly in the XML.
 
 Skin
+^^^^
+
 Skinned meshes (or skins) are meshes whose shape can deform at runtime. Their vertices are attached to rigid bodies
 (called bones in this context) and each vertex can belong to multiple bones, resulting in smooth deformations of the
 skin. Skins are purely visualization objects and do not affect the physics, but nevertheless they can enhance visual
@@ -375,6 +384,8 @@ Skin
 objects.
 
 Height field
+^^^^^^^^^^^^
+
 Height fields can be loaded from PNG files (converted to gray-scale internally) or from files in a custom binary
 format described later. A height field is a rectangular grid of elevation data. The compiler normalizes the data to
 the range [0-1]. The actual spatial extent of the height field is then determined by the size parameters of the
@@ -386,6 +397,8 @@ Height field
 the other objects in the simulation, so the number of contacts will be small for well-designed models.
 
 Texture
+^^^^^^^
+
 Textures can be loaded from PNG files or synthesized by the compiler based on user-defined procedural parameters.
 There is also the option to leave the texture empty at model creation time and change it later at runtime -- so as to
 render video in a MuJoCo simulation, or create other dynamic effects. The visualizer supports two types of texture
@@ -396,6 +409,8 @@ Texture
 only be referenced from another asset (namely material) which is then referenced from model elements.
 
 Material
+^^^^^^^^
+
 Materials are used to control the appearance of geoms, sites and tendons. This is done by referencing the material
 from the corresponding model element. Appearance includes texture mapping as well as other properties that interact
 with OpenGL lights below: RGBA, specularity, shininess, emission. Materials can also be used to make objects
@@ -417,6 +432,8 @@ within a body and belong to that body. This is in contrast with the stand-alone
 associated with a single body.
 
 Body
+^^^^
+
 Bodies have mass and inertial properties but do not have any geometric properties. Instead geometric shapes (or
 geoms) are attached to the bodies. Each body has two coordinate frames: the frame used to define it as well as to
 position other elements relative to it, and an inertial frame centered at the body's center of mass and aligned with
@@ -425,6 +442,8 @@ Body
 coordinates. This provides the basis for all subsequent computations.
 
 Joint
+^^^^^
+
 Joints are defined within bodies. They create motion degrees of freedom (DOFs) between the body and its parent. In
 the absence of joints the body is welded to its parent. This is the opposite of gaming engines which use
 over-complete Cartesian coordinates, where joints remove DOFs instead of adding them. There are four types of joints:
@@ -433,56 +452,9 @@ Joint
 ball and free joints are represented as unit quaternions, and all computations in MuJoCo respect the properties of
 quaternions.
 
-DOF
+Joint reference
-   Degrees of freedom are closely related to joints, but are not in one-to-one correspondence because ball and free
+'''''''''''''''
-   joints have multiple DOFs. Think of joints as specifying positional information, and of DOFs as specifying velocity
-   and force information. More formally, the joint positions are coordinates over the configuration manifold of the
-   system, while the joint velocities are coordinates over the tangent space to this manifold at the current position.
-   DOFs have velocity-related properties such as friction loss, damping, armature inertia. All generalized forces acting
-   on the system are expressed in the space of DOFs. In contrast, joints have position-related properties such as limits
-   and spring stiffness. DOFs are not specified directly by the user. Instead they are created by the compiler given the
-   joints.
 
-Geom
-   Geoms are 3D shapes rigidly attached to the bodies. Multiple geoms can be attached to the same body. This is
-   particularly useful in light of the fact that MuJoCo only supports convex geom-geom collisions, and the only way to
-   create non-convex objects is to represent them as a union of convex geoms. Apart from collision detection and
-   subsequent computation of contact forces, geoms are used for rendering, as well as automatic inference of body masses
-   and inertias when the latter are omitted. MuJoCo supports several primitive geometric shapes: plane, sphere, capsule,
-   ellipsoid, cylinder, box. A geom can also be a mesh or a height field; this is done by referencing the corresponding
-   asset. Geoms have a number of material properties that affect the simulation and visualization.
-
-Site
-   Sites are essentially light geoms. They represent locations of interest within the body frame. Sites do not
-   participate in collision detection or automated computation of inertial properties, however they can be used to
-   specify the spatial properties of other objects like sensors, tendon routing, and slider-crank endpoints.
-
-Camera
-   Multiple cameras can be defined in a model. There is always a default camera which the user can freely move with the
-   mouse in the interactive visualizer. However it is often convenient to define additional cameras that are either
-   fixed to the world, or are attached to one of the bodies and move with it. In addition to the camera position and
-   orientation, the user can adjust the field of view and the inter-pupilary distance for stereoscopic rendering, as
-   well as create oblique projections needed for stereoscopic virtual environments.
-
-Light
-   Lights can be fixed to the world body or attached to moving bodies. The visualizer provides access to the full
-   lighting model in OpenGL (fixed function) including ambient, diffuse and specular components, attenuation and cutoff,
-   positional and directional lighting, fog. Lights, or rather the objects illuminated by them, can also cast shadows.
-   However, similar to material reflections, each shadow-casting light adds one rendering pass so this feature should be
-   used with caution. Documenting the lighting model in detail is beyond the scope of this chapter; see `OpenGL
-   documentation <http://www.glprogramming.com/red/chapter05.html>`__ instead. Note that in addition to lights defined
-   by the user in the kinematic tree, there is a default headlight that moves with the camera. Its properties are
-   adjusted through the mjVisual options.
-
-.. _Standalone:
-
-Stand-alone elements
-~~~~~~~~~~~~~~~~~~~~
-
-Here we describe the model elements which do not belong to an individual body, and therefore are described outside the
-kinematic tree.
-
-Reference pose
 The reference pose is a vector of joint positions stored in ``mjModel.qpos0``. It corresponds to the numeric values
 of the joints when the model is in its initial configuration. In our earlier example the elbow was created in a bent
 configuration at 90° angle. But MuJoCo does not know what an elbow is, and so by default it treats this joint
@@ -496,14 +468,77 @@ Reference pose
 the quaternion saved in ``mjModel.qpos0`` is always (1,0,0,0) which corresponds to the null rotation. For free
 joints, the global 3D position and quaternion of the floating body are saved in ``mjModel.qpos0``.
 
-Spring reference pose
+Spring reference
+''''''''''''''''
+
 This is the pose in which all joint and tendon springs achieve their resting length. Spring forces are generated
 when the joint configuration deviates from the spring reference pose, and are linear in the amount of deviation. The
 spring reference pose is saved in ``mjModel.qpos_spring``. For slide and hinge joints, the spring reference is
 specified with the attribute springref. For ball and free joints, the spring reference corresponds to the initial
 model configuration.
 
+DOF
+^^^
+
+Degrees of freedom are closely related to joints, but are not in one-to-one correspondence because ball and free
+joints have multiple DOFs. Think of joints as specifying positional information, and of DOFs as specifying velocity
+and force information. More formally, the joint positions are coordinates over the configuration manifold of the
+system, while the joint velocities are coordinates over the tangent space to this manifold at the current position.
+DOFs have velocity-related properties such as friction loss, damping, armature inertia. All generalized forces acting
+on the system are expressed in the space of DOFs. In contrast, joints have position-related properties such as limits
+and spring stiffness. DOFs are not specified directly by the user. Instead they are created by the compiler given the
+joints.
+
+Geom
+^^^^
+
+Geoms are 3D shapes rigidly attached to the bodies. Multiple geoms can be attached to the same body. This is
+particularly useful in light of the fact that MuJoCo only supports convex geom-geom collisions, and the only way to
+create non-convex objects is to represent them as a union of convex geoms. Apart from collision detection and
+subsequent computation of contact forces, geoms are used for rendering, as well as automatic inference of body masses
+and inertias when the latter are omitted. MuJoCo supports several primitive geometric shapes: plane, sphere, capsule,
+ellipsoid, cylinder, box. A geom can also be a mesh or a height field; this is done by referencing the corresponding
+asset. Geoms have a number of material properties that affect the simulation and visualization.
+
+Site
+^^^^
+
+Sites are essentially light geoms. They represent locations of interest within the body frame. Sites do not
+participate in collision detection or automated computation of inertial properties, however they can be used to
+specify the spatial properties of other objects like sensors, tendon routing, and slider-crank endpoints.
+
+Camera
+^^^^^^
+
+Multiple cameras can be defined in a model. There is always a default camera which the user can freely move with the
+mouse in the interactive visualizer. However it is often convenient to define additional cameras that are either
+fixed to the world, or are attached to one of the bodies and move with it. In addition to the camera position and
+orientation, the user can adjust the field of view and the inter-pupilary distance for stereoscopic rendering, as
+well as create oblique projections needed for stereoscopic virtual environments.
+
+Light
+^^^^^
+
+Lights can be fixed to the world body or attached to moving bodies. The visualizer provides access to the full
+lighting model in OpenGL (fixed function) including ambient, diffuse and specular components, attenuation and cutoff,
+positional and directional lighting, fog. Lights, or rather the objects illuminated by them, can also cast shadows.
+However, similar to material reflections, each shadow-casting light adds one rendering pass so this feature should be
+used with caution. Documenting the lighting model in detail is beyond the scope of this chapter; see `OpenGL
+documentation <http://www.glprogramming.com/red/chapter05.html>`__ instead. Note that in addition to lights defined
+by the user in the kinematic tree, there is a default headlight that moves with the camera. Its properties are
+adjusted through the mjVisual options.
+
+.. _Standalone:
+
+Stand-alone
+~~~~~~~~~~~
+
+Here we describe the model elements which do not belong to an individual body, and therefore are described outside the
+kinematic tree.
+
 Tendon
+^^^^^^
+
 Tendons are scalar length elements that can be used for actuation, imposing limits and equality constraints, or
 creating spring-dampers and friction loss. There are two types of tendons: fixed and spatial. Fixed tendons are
 linear combinations of (scalar) joint positions. They are useful for modeling mechanical coupling. Spatial tendons
@@ -515,6 +550,8 @@ Tendon
 multiple branches using pulleys.
 
 Actuator
+^^^^^^^^
+
 MuJoCo provides a flexible actuator model, with three components that can be specified independently. Together they
 determine how the actuator works. Common actuator types are obtained by specifying these components in a coordinated
 way. The three components are transmission, activation dynamics, and force generation. The transmission specifies how
@@ -525,6 +562,8 @@ Actuator
 turn mapped into a generalized force by the moment arms inferred from the transmission.
 
 Sensor
+^^^^^^
+
 MuJoCo can generate simulated sensor data which is saved in the global array ``mjData.sensordata``. The result is not
 used in any internal computations; instead it is provided because the user presumably needs it for custom computation
 or data analysis. Available sensor types include touch sensors, inertial measurement units (IMUs), force-torque
@@ -536,6 +575,8 @@ Sensor
 and instead has to be done programmatically, as illustrated in the code sample :ref:`simulate.cc <saSimulate>`.
 
 Equality
+^^^^^^^^
+
 Equality constraints can impose additional constraints beyond those already imposed by the kinematic tree structure
 and the joints/DOFs defined in it. They can be used to create loop joints, or in general model mechanical coupling.
 The internal forces that enforce these constraints are computed together with all other constraint forces. The
@@ -544,6 +585,8 @@ Equality
 the positions of two joints or two tendons via a cubic polynomial.
 
 Contact pair
+^^^^^^^^^^^^
+
 Contact generation in MuJoCo is an elaborate process. Geom pairs that are checked for contact can come from two
 sources: automated proximity tests and other filters collectively called "dynamic", as well as an explicit list of
 geom pairs provided in the model. The latter is a separate type of model element. Because a contact involves a
@@ -552,6 +595,8 @@ Contact pair
 pairs that were removed by an aggressive filtering scheme.
 
 Contact exclude
+^^^^^^^^^^^^^^^
+
 This is the opposite of contact pairs: it specifies pairs of bodies (rather than geoms) which should be excluded from
 the generation of candidate contact pairs. It is useful for disabling contacts between bodies whose geometry causes
 an undesirable permanent contact. Note that MuJoCo has other mechanisms for dealing with this situation (in
@@ -559,6 +604,8 @@ Contact exclude
 automated mechanisms are not sufficient and explicit exclusion becomes necessary.
 
 Custom numeric
+^^^^^^^^^^^^^^
+
 There are three ways to enter custom numbers in a MuJoCo simulation. First, global numeric fields can be defined in
 the XML. They have a name and an array of real values. Second, the definition of certain model elements can be
 extended with element-specific custom arrays. This is done by setting the attributes ``nuser_XXX`` in the XML element
@@ -567,17 +614,23 @@ Custom numeric
 ``mjData`` and not in ``mjModel``.
 
 Custom text
+^^^^^^^^^^^
+
 Custom text fields can be saved in the model. They can be used in custom computations - either to specify keyword
 commands, or to provide some other textual information. Do not use them for comments though; there is no benefit to
 saving comments in a compiled model. XML has its own commenting mechanism (ignored by MuJoCo's parser and compiler)
 which is more suitable.
 
 Custom tuple
+^^^^^^^^^^^^
+
 Custom tuples are lists of MuJoCo model elements, possibly including other tuples. They are not used by the
 simulator, but are available for specifying groups of elements that are needed for user code. For example, one can
 use tuples to define pairs of bodies for custom contact processing.
 
 Keyframe
+^^^^^^^^
+
 A keyframe is a snapshot of the simulation state variables. It contains the vectors of joint positions, joint
 velocities, actuator activations when present, and the simulation time. The model can contain a library of keyframes.
 They are useful for resetting the state of the system to a point of interest. Note that keyframes are not intended