Refresh and de-duplicate install instructions for users and developers

.gitignore

@@ -37,3 +37,5 @@ gambit
 .python-version
 dist
 .venv
+*.dmg
+Gambit.app/*

doc/developer.build.rst

@@ -1,143 +1,162 @@
+.. _building-from-source:
+
 Building Gambit from source
 ===========================
 
-This section covers instructions for building Gambit from source.
+This page covers instructions for building Gambit from source.
 This is for those who are interested in developing Gambit, or who
 want to play around with the latest features before they make it
 into a pre-compiled binary version.
 
-This section requires at least some familiarity with programming.
-Most users will want to stick with binary distributions; see
-:ref:`section-downloading` for how to get the current version for
+This page requires at least some familiarity with programming.
+Most users will want to stick with released distributions; see the 
+:ref:`install` page for how to get the current version for
 your operating system.
+Following the instructions here will install the Gambit CLI, GUI and Python extension (PyGambit).
 
-General information
--------------------
+The steps you will need to follow to build from source are as follows:
 
-Gambit uses the standard autotools mechanism for configuring and building.
-This should be familiar to most users of Un*ces and MacOS X.
+1. Refer to the :ref:`contributor page <contributing-code>` which explains how to clone the Gambit repository from GitHub (you may first wish to create a fork).
+2. :ref:`Install the necessary build tools and dependencies for your platform <source-dependencies>`.
+3. :ref:`Follow the platform-specific instructions to build and install Gambit CLI and GUI components from source <cli-gui-from-source>`.
+4. :ref:`Build the Python extension (PyGambit) <build-python>`.
 
-If you are building from a source tarball,
-you just need to unpack the sources, change directory to the top level
-of the sources (typically of the form gambit-xx.y.z), and do the
-usual ::
+.. _source-dependencies:
 
-  ./configure
-  make
-  sudo make install
+Install build tools and dependencies
+------------------------------------
 
-Command-line options are available to modify the configuration process;
-do `./configure --help` for information.  Of these, the option which
-may be most useful is to disable the build of the graphical interface
+.. dropdown:: Install on macOS via Homebrew
+   :class-container: sd-border-0
+
+   1. Check that you have Homebrew installed by running `brew --version`. If not, follow the instructions at `https://brew.sh/ <https://brew.sh/>`_.
 
-By default Gambit will be installed in /usr/local.  You can change this
-by replacing configure step with one of the form ::
+   2. Install build dependencies:
 
-  ./configure --prefix=/your/path/here
+      .. code-block:: bash
 
-.. note::
-  The graphical interface relies on external calls to other
-  programs built in this process, especially for the computation of
-  equilibria.  It is strongly recommended that you install the Gambit
-  executables to a directory in your path!
+         brew install automake autoconf libtool wxwidgets
+
+      .. note::
+         If you encounter interpreter errors with autom4te, you may need to ensure
+         your Perl installation is correct or reinstall the autotools:
+
+         .. code-block:: bash
+
+            brew reinstall automake autoconf libtool wxwidgets
+
+.. dropdown:: Install on Linux (Debian/Ubuntu) via apt
+   :class-container: sd-border-0
+
+   1. Update your package lists:
 
+      .. code-block:: bash
 
-Building from git repository
-----------------------------
+         sudo apt update
 
-If you want to live on the bleeding edge, you can get the latest
-version of the Gambit sources from the Gambit repository on
-github.com, via ::
+   2. Install general build dependencies:
 
-  git clone https://github.com/gambitproject/gambit.git
-  cd gambit
+      .. code-block:: bash
 
-After this, you will need to set up the build scripts by executing ::
+         sudo apt install build-essential automake autoconf libtool
 
-  aclocal
-  libtoolize
-  automake --add-missing
-  autoconf
+   3. Install GUI dependencies (replace X.X with the latest version available, e.g., 3.2):
 
-For this, you will need to have automake, autoconf, and libtool2
-installed on your system.
+      .. code-block:: bash
 
-At this point, you can then continue with the configuration and build
-stages as in the previous section.
+         sudo apt-cache search libwxgt*
+         sudo apt install libwxgtkX.X-dev
 
-In the git repository, the branch ``master`` always points to the
-latest development version.  New development should in general always
-be based off this branch.  Branches labeled ``maintVV``, where ``VV``
-is the version number, point to the latest commit on a stable
-version.
+      .. note::
+         Note that Gambit requires wxWidgets version 3.2.x or higher.
 
+.. dropdown:: Install on Windows
+   :class-container: sd-border-0
 
-For Windows users
------------------
+    .. warning::
+       TODO: Add Windows build dependencies instructions here.
 
-For Windows users wanting to compile Gambit on their own, you'll need
-to use either the Cygwin or MinGW environments.  We do compilation and
-testing of Gambit on Windows using MinGW.
+.. _cli-gui-from-source:
 
+Install CLI and GUI from source
+--------------------------------
 
-For OS X users
---------------
+.. dropdown:: Install on Windows
+   :class-container: sd-border-0
 
-For building the command-line tools only, one should follow the
-instructions for Un*x/Linux platforms above.
+    .. warning::
+       For Windows users wanting to compile Gambit on their own, you'll need to use either the Cygwin or MinGW environments.  We do compilation and testing of Gambit on Windows using MinGW.
 
+The rest of these instructions are applicable to **Linux** and **macOS** users.
+Navigate to the Gambit source directory and run:
 
-The graphical interface and wxWidgets
--------------------------------------
+.. code-block:: bash
 
-Gambit requires wxWidgets version 3.1.x or higher.
-See the wxWidgets website at
-`<http://www.wxwidgets.org>`_
-to download this if you need it.  Packages of this should be available
-for most Un*x users through their package managers (apt or rpm).  Note
-that you'll need the appropriate -dev package for wxWidgets to get the
-header files needed to build Gambit.
+    aclocal
+    libtoolize
+    automake --add-missing
+    autoconf
+    ./configure
+    make
+    sudo make install
 
-Un*x users, please note that Gambit at this time only supports the
-GTK port of wxWidgets.
+.. note::
+  If you don't want to build the graphical interface, you can pass the argument `--disable-gui` to the configure step, for example, ::
 
-If wxWidgets it isn't installed in a standard place (e.g., /usr or
-/usr/local), you'll need to tell configure where to find it with the
---with-wx-prefix=PREFIX option, for example::
+  `./configure --disable-gui`
 
-  ./configure --with-wx-prefix=/home/mylogin/wx
+.. warning::
+  For Linux users:
+  If wxWidgets it isn't installed in a standard place (e.g., /usr or
+  /usr/local), you'll need to tell configure where to find it with the
+  `--with-wx-prefix=PREFIX` option, for example::
 
-Finally, if you don't want to build the graphical interface, you
-can either (a) simply not install wxWidgets, or (b) pass the argument
---disable-gui to the configure step, for example, ::
+    `./configure --with-wx-prefix=/home/mylogin/wx`
 
-  ./configure --disable-gui
+.. note::
+  Command-line options are available to modify the configuration process;
+  do `./configure --help` for information.  Of these, the option which
+  may be most useful is to disable the build of the graphical interface.
 
-This will just build the command-line tools, and will not require
-a wxWidgets installation.
+  By default Gambit will be installed in /usr/local.  You can change this
+  by replacing configure step with one of the form ::
 
-For OS X users, after the usual ``make`` step, run
+  `./configure --prefix=/your/path/here`
 
-  make osx-bundle
+.. warning::
+  The graphical interface relies on external calls to other
+  programs built in this process, especially for the computation of
+  equilibria.  It is strongly recommended that you install the Gambit
+  executables to a directory in your path!
 
-This produces an application ``Gambit.app`` in the current directory,
-which can be run from its current location, or copied elsewhere in the
-disk (such as ``/Applications``).  The application bundle includes the
-command-line executables.
+.. dropdown:: Build macOS application bundle
+   :class-container: sd-border-0
 
+   1. **Create macOS application bundle:**
 
+      To create a distributable DMG file:
+
+      .. code-block:: bash
+
+         make osx-dmg
+
+   2. **Install the application:**
+
+      After creating the DMG file, open it and drag the Gambit application to your Applications folder.
 
 .. _build-python:
 
 Building the Python extension
 -----------------------------
 
 The :ref:`pygambit Python package <pygambit>` is in ``src/pygambit``
-in the Gambit source tree.
-Building the extension follows the standard approach.
-From the **root directory of the source tree** execute
+in the Gambit source tree. We recommend to install `pygambit`
+as part of a virtual environment rather than in the system's Python.
+Use `pip` to install from the **root directory of the source tree**, optionally including the `-e` flag for an editable install:
+
+.. code-block:: bash
 
-    python -m pip install .
+   pip install -e .
 
 There is a set of test cases in `src/pygambit/tests`, which can be run
 using `nose2`.