[Docs] Update macOS installation guide for new release (#358)

doc/dev/installation.rst

@@ -2,17 +2,17 @@ Installation
 ============
 
 
-Catalyst is officially supported on Linux (x86_64) and macOS (aarch64) platforms, and pre-built binaries
-are being distributed via the Python Package Index (PyPI) for Python versions 3.9 and higher. To install
-it, simply run the following ``pip`` command:
+Catalyst is officially supported on Linux (x86_64) and macOS (aarch64, x86_64) platforms, and
+pre-built binaries are being distributed via the Python Package Index (PyPI) for Python versions
+3.9 and higher. To install it, simply run the following ``pip`` command:
 
 .. code-block:: console
 
     pip install pennylane-catalyst
 
 
-Pre-built packages for Windows and MacOS are not yet available, and comptability with those
-platforms is untested and cannot be guaranteed. If you are using one of these platforms, please
+Pre-built packages for Windows are not yet available, and comptability with other platforms is
+untested and cannot be guaranteed. If you are using one of these platforms, please
 try out our Docker and Dev Container images described in the `next section <#dev-containers>`_.
 
 If you wish to contribute to Catalyst or develop against our runtime or compiler, instructions for
@@ -46,6 +46,7 @@ source, and requires launching the post-install script at ``.devcontainer/dev/po
 from whithin the root of the running container.
 
 .. note::
+
   Due to `a bug <https://github.com/microsoft/vscode-remote-release/issues/8412>`_ in the Dev
   Containers extension, clicking on the "Launch" badge will not prompt for a choice between the User
   and Dev containers. Instead, the User container is automatically chosen.
@@ -58,69 +59,75 @@ Building from source
 --------------------
 
 
-To build Catalyst from its source code, developers should follow the
-instructions provided below for building all three modules: the Python
-frontend, the MLIR compiler, and runtime library.
+To build Catalyst from source, developers should follow the instructions provided below for building
+all three modules: the Python frontend, the MLIR compiler, and the runtime library.
 
 Requirements
 ^^^^^^^^^^^^
 
 
-In order to build Catalyst from source, developers need to ensure the
-following pre-requisites are installed and available on the path:
+In order to build Catalyst from source, developers need to ensure the following pre-requisites are
+installed and available on the path (depending on the platform):
 
-- The `clang <https://clang.llvm.org/>`_ compiler, `LLD
-  <https://lld.llvm.org/>`_ linker, `CCache <https://ccache.dev/>`_ compiler
-  cache, and `OpenMP <https://www.openmp.org/>`_.
+- The `clang <https://clang.llvm.org/>`_ compiler, `LLD <https://lld.llvm.org/>`_ linker
+  (Linux only), `CCache <https://ccache.dev/>`_ compiler cache (optional, recommended), and
+  `OpenMP <https://www.openmp.org/>`_ (Linux only).
 
-- The `Ninja <https://ninja-build.org/>`_, `Make
-  <https://www.gnu.org/software/make/>`_, and `CMake
-  <https://cmake.org/download/>`_ (v3.20 or greater) build tools.
+- The `Ninja <https://ninja-build.org/>`_, `Make <https://www.gnu.org/software/make/>`_, and
+  `CMake <https://cmake.org/download/>`_ (v3.20 or greater) build tools.
 
 - `Python <https://www.python.org/>`_ 3.9 or higher for the Python frontend.
 
-- ``pip`` must be version 22.3 or higher.
+- The Python package manager ``pip`` must be version 22.3 or higher.
 
-They can be installed on Debian/Ubuntu via:
+They can be installed on **Debian/Ubuntu** via:
 
 .. code-block:: console
 
   sudo apt install clang lld ccache libomp-dev ninja-build make cmake
 
-They can be installed on macOS via:
+.. Note::
+
+  If the CMake version available in your system is too old, you can also install up-to-date
+  versions of it via ``pip install cmake``.
+
+On **macOS**, it is strongly recommended to install the official XCode Command Line Tools
+(for ``clang`` & ``make``). The remaining packages can then be installed via ``pip``:
 
 .. code-block:: console
 
-  brew install cmake ninja
+  pip install cmake ninja
 
 If you install Catalyst on a macOS system with ``ARM`` architecture (e.g. Apple M1/M2), you
 additionally need to install `Rust <https://www.rust-lang.org/tools/install>`_ and the
 ``llvm-tools-preview`` rustup component:
 
 .. code-block:: console
 
+  curl https://sh.rustup.rs -sSf | sh
+  source "$HOME/.cargo/env"
   rustup component add llvm-tools-preview
 
-.. Note::
-  If the CMake version available in your system is too old, you can also install up-to-date
-  versions of it via ``pip install cmake``.
-
 All additional build and developer dependencies are managed via the repository's
 ``requirements.txt`` and can be installed as follows:
 
 .. code-block:: console
 
   pip install -r requirements.txt
 
-Once the pre-requisites are installed, start by cloning the project repository
-including all its submodules:
+.. Note::
+
+  Please ensure that your local site-packages for Python are available on the ``PATH`` - watch out
+  for the corresponding warning that ``pip`` may give you during installation.
+
+Once the pre-requisites are installed, start by cloning the project repository including all its
+submodules:
 
 .. code-block:: console
 
-  git clone --recurse-submodules --shallow-submodules -j2 https://github.com/PennyLaneAI/catalyst.git
+  git clone --recurse-submodules --shallow-submodules https://github.com/PennyLaneAI/catalyst.git
 
-For an existing copy of the repository without its submodules, they can also
-be fetched via:
+For an existing copy of the repository without its submodules, they can also be fetched via:
 
 .. code-block:: console
 
@@ -129,22 +136,15 @@ be fetched via:
 Catalyst
 ^^^^^^^^
 
-The build process for Catalyst is managed via a series of Makefiles for each
-component. To build the entire project from start to finish simply run the
-following make target from the top level directory:
+The build process for Catalyst is managed via a series of Makefiles for each component. To build
+the entire project from start to finish simply run the following make target from the top level
+directory:
 
 .. code-block:: console
 
   make all
 
-To build the project on macOS with ``ARM`` architecture (e.g. Apple M1/M2):
-
-.. code-block:: console
-
-  BUILD_QIR_STDLIB_FROM_SRC=ON ENABLE_LLD=OFF make all
-
-To build each component one by one starting from the runtime, you can follow
-the instructions below.
+To build each component one by one starting from the runtime, you can follow the instructions below.
 
 Runtime
 """""""
@@ -162,7 +162,9 @@ directory:
 
 The runtime supports multiple backend devices, enabling the execution of quantum
 circuits locally on CPUs and GPUs, and remotely on Amazon Braket NISQ hardware.
-A list of supported backends, along with Make arguments for each device, is available in the `Catalyst Runtime <https://docs.pennylane.ai/projects/catalyst/en/latest/modules/runtime.html>`_ page.
+A list of supported backends, along with Make arguments for each device, is available in the
+`Catalyst Runtime <https://docs.pennylane.ai/projects/catalyst/en/latest/modules/runtime.html>`_
+page.
 
 MLIR Dialects
 """""""""""""