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

.gitignore

@@ -65,4 +65,8 @@ lib/*
 build/
 !.github/actions/build/
 !.github/actions/build/**
+
+# Documentation
+!docs/source/Build/
+
 *.git-template

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,28 @@
+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
+   Build/pipInstall

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,22 +3,18 @@
 
 .. _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::
 
@@ -44,16 +40,10 @@ Build options (as passed to ``conanfile.py`` and described in :ref:`configureBui
     installations (``pip install -e .``) are not currently supported. Please follow the standard
     :ref:`configureBuild` process.
 
-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 .
@@ -100,29 +90,6 @@ The following command is used to both download the code and compile Basilisk wit
 
     pip install git+https://github.com/AVSLab/basilisk.git
 
-Wheel Compatibility
--------------------
-
-.. warning::
-
-    Wheel compatibility is currently being verified across Python versions and different platforms. So far,
-    some users have reported successfully installing the same wheel on different Ubuntu versions and with
-    different Python versions, but your mileage may vary.
-
-    If you choose to try this feature and run into and problems, please `raise an issue
-    <https://github.com/AVSLab/basilisk/issues>`_ for the Basilisk maintainers to investigate.
-
-When installed using a standard Python packaging tool such as ``pip``, Basilisk will automatically be
-built using the `Python Limited C API <https://docs.python.org/3/c-api/stable.html#limited-c-api>`_. The
-resulting wheel file will contain a set of compiled Python extension modules that, at least in theory, can be
-run using any compatible Python version (currently, any from Python 3.8 to 3.11).
-
-To maintain backwards compatibility, standard Basilisk installations via ``python conanfile.py`` are not
-compatible between different Python versions, as is stated in :ref:`customPython`. However, users can
-also forcibly build with the Python Limited C API by providing the ``--pyLimitedAPI`` flag::
-
-    python conanfile.py --pyLimitedAPI 0x030800f0
-
 
 For Maintainers: Overview of Implementation
 -------------------------------------------
@@ -140,23 +107,12 @@ specified in ``pyproject.toml``). The builder then invokes ``python conanfile.py
 environment. The main reasons for this setting was to maintain the current default behaviour of
 ``conanfile.py``-based installation.
 
-Editable installations (i.e. ``pip install -e .``) are not currently supported for two main reasons:
-
-1. ``pip install -e .`` is currently overridden to maintain the existing ``python conanfile.py`` behaviour.
-2. Due to the underlying CMake build system, editable installs with ``pip`` require setting the
-   ``--no-build-isolation`` option, which means that the user must manually install the build requirements.
-   Since these build requirements are installed automatically by the standard ``conanfile.py`` installation,
-   it is the recommended method for editable installations.
-
-Tools such as `cibuildwheel <https://cibuildwheel.pypa.io/en/stable/>`_ can be used to build wheels that are
-automatically compatible with a broad range of operating system versions. These pre-compiled wheels can then
-be shared publicly using tools like `twine <https://pypi.org/project/twine/>`_ to upload them to the
-`Python Package Index (PyPi) <https://pypi.org/>`_, allowing users to simply ``pip install Basilisk``. We
-expect that these tools will be added into the Basilisk Continuous Integration pipeline in the future.
-
-Further discussions and implementation details can be found in
-`Basilisk merge request #737 <https://github.com/AVSLab/basilisk/pull/737>`_.
+Editable installations (i.e. ``pip install -e .``) are are partially supported. Python code changes are reflected
+automatically with this flag, but C++ components are not automatically rebuilt.
 
+This limitation exists because editable mode still routes through ``python conanfile.py``, but skips C++ rebuilds
+once the initial build exists. This avoids long native rebuilds and preserves the Conan/CMake configuration.
+...
 
 .. rubric:: Footnotes
 

docs/source/Install.rst

@@ -1,23 +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:
-
-   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 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/Support/bskReleaseNotes.rst

@@ -26,6 +26,7 @@ Basilisk Release Notes
 
 Version |release|
 -----------------
+- Improved documentation structure by separating build from source instructions from pip installation instructions.
 - Added custom reaction wheel: "NanoAvionics RW0" to ``src/utilities/simIncludeRW.py``
 - Added TLE handling utilities in :ref:`tleHandling` to parse TLE files and convert to orbital elements
 - Removed deprecated use of astro constants from ``src/utilities/astroFunction.py``.

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