Merge branch 'main' into chore-upload-sonarcloud-json

Author: asalzburger

README.md

@@ -34,6 +34,12 @@ guide](https://acts-project.github.io/building_acts.html). If you find a bug,
 have a feature request, or want to contribute to ACTS, have a look at the
 [contribution guidelines](CONTRIBUTING.md).
 
+### Python bindings
+
+ACTS is also available as a Python package via `pip install pyacts`. See the
+[Python bindings documentation](https://acts-project.github.io/python_bindings.html)
+for details.
+
 ## Versioning and public API
 
 Release versions follow [semantic versioning](https://semver.org/spec/v2.0.0.html)

docs/Doxyfile.in

@@ -774,7 +774,6 @@ WARN_LOGFILE           =
 INPUT                  = index.md \
                          groups \
                          pages \
-                         examples \
                          namespaces.dox \
                          experimental.md \
                          ../Core/include \

docs/DoxygenLayout.xml

@@ -21,10 +21,6 @@
 
     <tab type="user" url="@ref versioning" visible="yes" title="Versioning and public API"/>
 
-    <tab type="usergroup" title="Examples" url="[none]">
-      <tab type="user" url="@ref python_bindings" visible="yes" title="Python bindings"/>
-    </tab>
-
     <tab type="topics" visible="yes" title="" intro=""/>
 
 

docs/examples/python_bindings.md docs/groups/python_bindings.mddocs/examples/python_bindings.md renamed to docs/groups/python_bindings.md

@@ -1,16 +1,67 @@
-@page python_bindings Python Bindings for Examples
+@defgroup python_bindings Python Bindings
+@brief Python bindings for the ACTS tracking toolkit, available via PyPI or built from source.
 
-The examples part of ACTS ships with python bindings using the `pybind11`
-library. Building these bindings can be enabled via
-`-DACTS_BUILD_EXAMPLES_PYTHON_BINDINGS=ON`, and requires a python installation
-including the development files to be installed. You can then build the special
-target `ActsPythonBindings` to build everything that can be accessed in python.
+# Installation from PyPI
 
-The build will create a setup script in `$BUILD/this_acts_withdeps.sh` which
-modifies `$PYTHONPATH` so that you can import the `acts` module in python.
+The easiest way to get the ACTS Python bindings is via [PyPI](https://pypi.org/project/pyacts/):
 
-Here is a minimal example of a python script using the example bindings, which
-sets up the particle propagation and runs a few events.
+```console
+pip install pyacts
+```
+
+A nightly development build is also available from [TestPyPI](https://test.pypi.org/project/pyacts/):
+
+```console
+pip install -i https://test.pypi.org/simple pyacts
+```
+
+The `pyacts` distribution includes bindings for the core library, Fatras, and
+the Examples framework.
+
+> [!warning]
+> The PyPI package does not include all optional plugins (e.g. DD4hep/ODD, Geant4, ROOT).
+> To use those, build from source with the relevant CMake options enabled.
+
+> [!note]
+> Even though the name of the PyPI package is `pyacts`, the python module must be imported
+> as `import acts`.
+
+# Building from source
+
+To use the full Python bindings including optional components such as DD4hep/ODD, Geant4, ROOT, build ACTS from
+source with `ACTS_BUILD_PYTHON_BINDINGS=ON`.
+
+```console
+cmake -B <build> -S <source> -DACTS_BUILD_PYTHON_BINDINGS=ON
+```
+
+Bindings for additional components (plugins, Examples framework) are built automatically if
+they are enabled.
+
+```console
+cmake -B <build> -S <source> -DACTS_BUILD_PYTHON_BINDINGS=ON -DACTS_BUILD_EXAMPLES=ON
+```
+
+Building requires a Python installation including the development headers.
+You can then build the special target `ActsPythonBindings` to build everything
+that can be accessed from Python:
+
+```console
+cmake --build <build> -- ActsPythonBindings
+```
+
+The build creates a setup script `$BUILD/this_acts_withdeps.sh` which modifies
+`$PYTHONPATH` so that you can import the `acts` module in Python.
+
+> [!warning]
+> The old flag `ACTS_BUILD_EXAMPLES_PYTHON_BINDINGS` is **deprecated**.
+> Use `ACTS_BUILD_PYTHON_BINDINGS` (together with `ACTS_BUILD_EXAMPLES` if
+> needed) instead.
+
+# Minimal example
+
+Here is a minimal example of a Python script using the bindings, which sets up
+particle propagation and runs a few events.
 
 @snippet{trimleft} examples/test_generic.py Basic propagation example with GenericDetector
 
@@ -23,16 +74,16 @@ They can be found in `$REPO_ROOT/Examples/Scripts/Python`. Make sure you have ru
 source $BUILD/this_acts_withdeps.sh
 ```
 
-to make sure python can find the `acts` module.
+to make sure Python can find the `acts` module.
 
 ## Python based unit tests
 
 A number of unit tests based on the `pytest` library are shipped with the
 repository. They are located under `$REPO_ROOT/Examples/Python/tests`, and
-intend to cover the public API of the python bindings. A set of tests also
-executed the standalone example scripts.
+intend to cover the public API of the Python bindings. A set of tests also
+execute the standalone example scripts.
 
-To run these python based tests, `pytest` and a few other dependencies need
+To run these Python based tests, `pytest` and a few other dependencies need
 to be installed. They can be installed via `pip install -r
 Examples/Python/tests/requirements.txt` from the repository root.  You can
 then simply run `pytest` from the repository root.