Improve the build instructions for mac.

The app bundle doesn't include mujoco.framework, so the instructions were a bit stale. I verified that with these new instructions I'm able to build the Python bindings from source with a prebuilt MuJoCo binary.

Fixes #313.

PiperOrigin-RevId: 666272041
Change-Id: I8bcf14c8ab6268cdaa617a8b5940b155ef64a8c5

doc/programming/index.rst

@@ -76,24 +76,16 @@ directory; it contains error and warning messages, and can be deleted at any tim
 
 After verifying that the simulator works, you may also want to re-compile the code samples to ensure that you have a
 working development environment. We provide a cross-platform `CMake
-<https://github.com/google-deepmind/mujoco/blob/main/sample/CMakeLists.txt>`_ setup that can be used to build sample
+<https://github.com/google-deepmind/mujoco/blob/main/sample/CMakeLists.txt>`__ setup that can be used to build sample
 applications independently of the MuJoCo library itself.
 
 On macOS, the DMG disk image contains ``MuJoCo.app``, which you can double-click to launch the ``simulate`` GUI. You can
-also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app. While
+also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app. As well as the
-``MuJoCo.app`` may look like a file, it is in fact an `Application Bundle <https://developer.apple.com/go/?id=bundle-
+``MuJoCo.app`` `Application Bundle <https://developer.apple.com/go/?id=bundle-
-structure>`_, which is a directory that contains executable binaries for all of MuJoCo's sample applications, along with
+structure>`__, the DMG includes the ``mujoco.framework`` subdirectory containing the MuJoCo dynamic library and all of
-an embedded `framework
+its public headers. If you are using Xcode, you can import it as a framework dependency on your project. (This also
-<https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html>`_,
-which is a subdirectory containing the MuJoCo dynamic library and all of its public headers. In other words,
-``MuJoCo.app`` contains all the same files that are shipped in the archive on Windows and Linux. To see this, right
-click (or control-click) on ``MuJoCo.app`` and click "Show Package Contents".
-
-As mentioned above, ``mujoco.framework`` contains the library and headers that are necessary to build any application
-that depends on MuJoCo. If you are using Xcode, you can import it as a framework dependency on your project. (This also
 works for Swift projects without any modification). If you are building manually, you can use ``-F`` and
-``-framework mujoco`` to specify the header search path and the library search path respectively. The macOS Makefile
+``-framework mujoco`` to specify the header search path and the library search path respectively.
-provides an example for this.
 
 .. _inBuild:
 

doc/python.rst

@@ -522,8 +522,8 @@ Building from source
 1. Make sure you have CMake and a C++17 compiler installed.
 
 2. Download the `latest binary release <https://github.com/google-deepmind/mujoco/releases>`__
-   from GitHub. On macOS, the download corresponds to a DMG file from which you
+   from GitHub. On macOS, the download corresponds to a DMG file which you can mount by
-   can drag ``MuJoCo.app`` into your ``/Applications`` folder.
+   double-clicking or running ``hdiutil attach <dmg_file>``.
 
 3. Clone the entire ``mujoco`` repository from GitHub and ``cd`` into the python
    directory:
@@ -545,7 +545,6 @@ Building from source
 
    .. code-block:: shell
 
-      cd python
       bash make_sdist.sh
 
    The ``make_sdist.sh`` script generates additional C++ header files that are
@@ -556,19 +555,21 @@ Building from source
 
 6. Use the generated source distribution to build and install the bindings.
    You'll need to specify the path to the MuJoCo library you downloaded earlier
-   in the ``MUJOCO_PATH`` environment variable.
+   in the ``MUJOCO_PATH`` environment variable, and the path to the MuJoCo
+   plugin directory in the ``MUJOCO_PLUGIN_PATH`` environment variable.
 
    .. note::
-      For macOS, this can be the path to a directory that contains the
+      For macOS, the files need to be extracted from the DMG.
-      ``mujoco.framework``. In particular, you can set
+      Once you mounted it as in step 2, the ``mujoco.framework`` directory can be found in ``/Volumes/MuJoCo``,
-      ``MUJOCO_PATH=/Applications/MuJoCo.app`` if you installed MuJoCo as
+      and the plugins directory can be found in ``/Volumes/MuJoCo/MuJoCo.app/Contents/MacOS/mujoco_plugin``.
-      suggested in step 1.
+      Those two directories can be copied out somewhere convenient, or you can use
+      ``MUJOCO_PATH=/Volumes/MuJoCo MUJOCO_PLUGIN_PATH=/Volumes/MuJoCo/MuJoCo.app/Contents/MacOS/mujoco_plugin``.
 
    .. code-block:: shell
 
       cd dist
-      MUJOCO_PATH=/PATH/TO/MUJOCO
+      MUJOCO_PATH=/PATH/TO/MUJOCO \
-      MUJOCO_PLUGIN_PATH=/PATH/TO/MUJOCO_PLUGIN
+      MUJOCO_PLUGIN_PATH=/PATH/TO/MUJOCO_PLUGIN \
       pip install mujoco-x.y.z.tar.gz
 
 The Python bindings should now be installed! To check that they've been