Separate documentation into "Install" and "Build from Source"

.gitignore

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

README.md

@@ -1,32 +1,56 @@
 # README
 
-### Basilisk
+## Basilisk
 
 * [Summary of Basilisk](docs/source/index.rst)
 * [Release Notes](docs/source/Support/bskReleaseNotes.rst)
 
-### How do I get set up?
-The following links contain installation instructions for the supported platforms:
+### Installation
 
-- [Setup a macOS Development Environment](docs/source/Install/installOnMacOS.rst)
+Basilisk can be installed in two ways, either from PyPI or by building from
+source.
 
-- [Setup a Linux Development Environment](docs/source/Install/installOnLinux.rst)
+For most users, installing from PyPI is the easiest and fastest way to get
+started. Building from source is recommended if you need to link to external
+C++ modules or want to customize the build configuration.
 
-- [Setup a Windows Development Environment](docs/source/Install/installOnWindows.rst)
+#### Install from PyPI
 
+The easiest way to get started with Basilisk is to install the prebuilt wheel
+from [PyPI](https://pypi.org/project/bsk/):
 
+```bash
+pip install bsk
+```
+
+This installs the latest stable version with all standard features
+(e.g. optical navigation and MuJoCo). See the [install](docs/source/Install.rst)
+docs for supported platforms and additional details about the wheels.
+
+#### Build from Source
+
+If you need to use external C++ modules or want to customize the build, follow
+the platform-specific setup instructions:
+
+* [Setup a macOS Development Environment](docs/source/Build/installOnMacOS.rst)
+
+* [Setup a Linux Development Environment](docs/source/Build/installOnLinux.rst)
+
+* [Setup a Windows Development Environment](docs/source/Build/installOnWindows.rst)
+
+See the [Build from Source docs](docs/source/Build.rst) for full details.
 
 ### Basilisk Development guidelines
 
 * [Contributing](CONTRIBUTING.md)
 * [Coding Guidelines](docs/source/Support/Developer/CodingGuidlines.rst)
 
-
 ### Getting Started
+
 To get started with Basilisk (BSK), several tutorial python files are provided in the installed package.  Within this
-web page documentation site, they are listed and discussed in the [integrated example script](docs/source/examples/index.rst)
-page.  The
-documentation lists the scenarios in an order that facilitates learning basic BSK features. The python scripts
+web page documentation site, they are listed and discussed in the [integrated example script](docs/source/examples/index.rst) page.
+
+The documentation lists the scenarios in an order that facilitates learning basic BSK features. The python scripts
 are stored under `basilisk/examples`. A good start would be to run `scenarioBasicOrbit.py`.
 
 To play with the tutorials, it is suggested the user makes a copy of these tutorial files, and use the copies in order
@@ -39,13 +63,12 @@ Now, when you want to use a tutorial, navigate inside that folder, and edit and
 
 Any new BSK module development should not occur within the BSK folder as this will be updated rapidly.  Rather,
 new FSW algorithm or simulation code modules should be created in a custom folder outside of the BSK directory.
-See the [building custom modules](docs/source/Install/buildExtModules.rst) web page
+See the [building custom modules](docs/source/Build/buildExtModules.rst) web page
 for more information.
 
 To use the standalone 3D Visualization, download the [Vizard](docs/source/Vizard/VizardDownload.rst).
 This is in development, but does provide a 3D view of many of the simulation states.
 
-
 ### Who do I talk to?
 
 Questions and answers are fielded in the project's [Github Discussions](https://github.com/AVSLab/basilisk/discussions).

docs/source/Build.rst

@@ -0,0 +1,27 @@
+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/pullCloneBSK
+   Build/installOnLinux
+   Build/installOnMacOS
+   Build/installOnWindows
+   Build/installBuild
+   Build/buildExtModules
+   Build/customPython
+   Build/installBuildConan

docs/source/Install/buildExtModules.rst → docs/source/Build/buildExtModules.rst

@@ -11,7 +11,7 @@ Motivation
 ----------
 .. sidebar:: Source Code
 
-    An example external folder with custom Basilisk modules and message definitions can be downloaded :download:`here </../../docs/source/Install/External.zip>`.
+    An example external folder with custom Basilisk modules and message definitions can be downloaded :download:`here </../../docs/source/Build/External.zip>`.
 
 
 It is preferred that the user not put their own modules inside the official Basilisk folder unless this module is intended to be pushed back to the repository.  This keeps the official Basilisk folder free from local customizations and thus easier to keep up to date.  With Basilisk 2.0 and onwards the user has the ability to create modules which are not included in basilisk repository.  The new build system allows a single folder containing custom BSK modules to be included into a single Basilisk build. This document outlines how this is done.  The resulting build product will contain both the official Basilisk modules as well as modules available within this external folder.
@@ -70,5 +70,3 @@ Frequently Asked Questions
     - The custom Basilisk modules are built into a ``Basilisk.ExternalModules`` package.  For example, to load a module called ``customCppModule``, use::
 
         from Basilisk.ExternalModules import customCppModule
-
-

docs/source/Install/pipInstall.rst → docs/source/Build/pipInstall.rst

@@ -3,21 +3,17 @@
 
 .. _pipInstall:
 
-Advanced: Building and Installing Pre-Compiled Basilisk Wheels
-==============================================================
+Advanced: Building Pre-Compiled Basilisk Wheels
+===============================================
 
-.. warning::
-
-    :beta:`Pip Wheel Support` This method of building Basilisk is currently a beta feature, and should only be attempted by advanced users
-    familiar with `Python packaging and distribution
-    <https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/>`_.
-    This method is not yet guaranteed to work on every platform, and there are still some annoyances
-    to iron out, but we appreciate any feedback you may have.
+The following instructions explain how to build wheels with Basilisk.
+While we distribute pre-compiled wheels already in :ref:`bskInstall`,
+you can also build them manually using the steps below. This is desirable if
+you want to use Python wheels but still need to enable custom build options
+or link against a custom external module location.
 
-    Most users should see :ref:`configureBuild` for documentation on the regular build process.
 
-
-Building and Installing with ``pip``
+Building Wheels and Installing with ``pip``
 ------------------------------------
 
 .. note::
@@ -49,11 +45,6 @@ After installing
 Building Basilisk ``wheel`` File
 --------------------------------
 
-On its own, there is no significant benefit to installing Basilisk in this way. However, supporting standard Python
-packaging tools means that Basilisk can now be built into a pre-compiled `"wheel" (.whl) file
-<https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#wheels>`_ that can be shared
-and installed on other compatible machines.
-
 Using ``pip``, the command below will generate a ``Basilisk-*.whl`` file in the current directory::
 
     pip wheel --no-deps -v .

docs/source/Install.rst

@@ -1,23 +1,70 @@
-.. 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:
-
-   Install/pullCloneBSK
-   Install/installOnLinux
-   Install/installOnMacOS
-   Install/installOnWindows
-   Install/installBuild
-   Install/buildExtModules
-   Install/customPython
-   Install/installBuildConan
-   Install/pipInstall
+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 standard features, 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 Python **3.8 and newer**.
+
+.. 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

@@ -200,8 +200,10 @@ Related Publications
 .. toctree::
    :maxdepth: 1
    :caption: Basilisk:
+   :includehidden:
 
    Install
+   Building from Source <Build>
    Learn
    Support
    Documentation/index