Add new pip install instructions

Author: ReeceHumphreys

.gitignore

@@ -62,3 +62,7 @@ venv/
 build/
 !.github/actions/build/
 !.github/actions/build/**
+
+# Documentation
+!docs/source/Build/
+*.git-template

docs/source/Build.rst

@@ -1,16 +1,28 @@
-Build
-=====
+Building from Source
+====================
+
+.. _bskInstall-build:
+
+For advanced users and developers who want to customize or debug Basilisk. For
+most users the precompiled version available on PyPI is sufficient. See the
+:ref:`Install Instructions <bskInstall>` for more information.
+
+.. note::
+   To use custom C++ modules, Basilisk must be built from source.
+   The prebuilt PyPI wheels are designed for most users and include all standard
+   features, but they do not yet support linking external C++ modules.
+   We're actively exploring ways to enable this in future releases.
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
-   Build/customPython
    Build/pullCloneBSK
    Build/installOnLinux
    Build/installOnMacOS
    Build/installOnWindows
    Build/installBuild
    Build/buildExtModules
+   Build/customPython
    Build/installBuildConan
    Build/pipInstall

docs/source/Install.rst

@@ -1,13 +1,71 @@
-.. Basilisk documentation master file, created by
-   sphinx-quickstart on Mon Sep 23 13:52:19 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 .. _bskInstall:
 
 Install
 =======
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+Basilisk can be installed either from `PyPI <https://pypi.org/project/bsk/>`_ as
+a prebuilt wheel or built locally from source.
+The prebuilt wheels include all build options, such as optical navigation
+and MuJoCo dynamics, but do **not** support linking external C++ modules, as
+this requires rebuilding Basilisk.
+
+If you want to use custom C++ modules, or prefer smaller install sizes by
+excluding unused features, you must build Basilisk from source.
+See the :ref:`Building from Source <bskInstall-build>` for more information.
+
+.. note::
+   We are currently investigating ways to allow users to link external C++
+   modules while using the prebuilt PyPI wheel. Stay tuned!
+
+
+The easiest way to install Basilisk is using ``pip`` to install the prebuilt
+package from PyPI. Run:
+
+.. code-block:: bash
+
+   pip install bsk
+
+Or, if using `uv <https://docs.astral.sh/uv/>`_ (a modern Python package manager):
+
+.. code-block:: bash
+
+   uv pip install bsk
+
+This installs the latest stable version of Basilisk and all dependencies.
+To install a specific version, run:
+
+.. code-block:: bash
+
+   pip install bsk==<version>
+
+Replace ``<version>`` with the desired release number, e.g. ``2.0.0``.
+
+
+**Prebuilt wheel availability:**
+
+- **Windows:** Windows 10/11 (x86_64)
+- **macOS:** macOS 11+ (x86_64 and Apple Silicon arm64)
+- **Linux:** Manylinux 2.24+ (x86_64, aarch64)
+
+All wheels are built as **ABI3** packages for Basilisk supported Python
+versions.
+
+.. note::
+   On unsupported systems or Python versions, ``pip`` will automatically
+   download the source archive (``.tar.gz``) and build Basilisk locally.
+   This requires a C++ compiler toolchain and standard build tools
+   to be installed on your system.
+
+To keep the wheel size smaller, the large BSK data files are not installed by
+default.  If the user wants to use script that assumes they are included into
+the Basilisk python package, then go to the command line, change the current
+directory to be inside the environment where Basilisk was ``pip`` installed,
+and run the command::
+
+    bskLargeData
+
+This command runs a python file stored in the ``src/utilities`` folder.
+The ``pip install`` process automatically
+creates this console command in the current python environment to call this
+python file.  The file directly downloads the missing large BSK data files and put
+them into the local Basilisk python package installation.

docs/source/index.rst

@@ -203,7 +203,7 @@ Related Publications
    :includehidden:
 
    Install
-   Build
+   Building from Source <Build>
    Learn
    Support
    Documentation/index