Add documentation for using local Mantid builds with pixi environments (#39724)

Added documentation explaining how to configure pixi environments to use local Mantid builds instead of conda packages in dependent projects.

#### Purpose of work
This documentation addresses the need for developers working on projects that depend on Mantid (like SNAPRed) to easily test their Mantid changes without having to publish and install new conda packages. It enables simultaneous development and testing across both Mantid and dependent codebases.

*There is no associated issue.*

#### Further detail of work
Created comprehensive documentation (`LocalMantidBuildWithPixi.rst`)
that covers:
- Prerequisites for setting up local Mantid builds with pixi
- Complete pixi configuration examples for `pyproject.toml`
- Required environment variables (PYTHONPATH, LD_LIBRARY_PATH,
MANTIDPATH, etc.)
- Usage instructions for installing and running the environment
- Troubleshooting guide for common setup issues
- References to related Mantid documentation

The documentation is based on the implementation pattern used in SNAPRed [PR #616](neutrons/SNAPRed#616) and provides a reusable guide for other projects that need similar functionality.

Author: darshdinger

dev-docs/source/LocalMantidBuildWithPixi.rst

@@ -0,0 +1,98 @@
+.. _LocalMantidBuildWithPixi:
+
+====================================================
+Using Local Mantid Build in Other Projects with Pixi
+====================================================
+
+.. contents::
+  :local:
+
+Overview
+########
+
+This guide shows how to configure a pixi environment to use your local Mantid build instead of the conda package in other projects that depend on Mantid. This is useful when you need to develop and test changes across both Mantid and dependent applications simultaneously.
+
+Prerequisites
+#############
+
+* A successfully built local Mantid installation (see :ref:`BuildingWithCMake`)
+* `Pixi <https://pixi.ws/latest/>`_ installed
+* Your dependent project with pixi configuration
+
+Configuration
+#############
+
+Add a new pixi environment to your project's ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+    [tool.pixi.environments]
+    local-mantid = { features = ["local-mantid"], solve-group = "default" }
+
+    [tool.pixi.feature.local-mantid.dependencies]
+    # Include your project's dependencies but exclude mantid packages
+    python = ">=3.10"
+    numpy = "*"
+    # ... other dependencies (do NOT include mantid, mantidworkbench, mantidqt)
+
+    [tool.pixi.feature.local-mantid.activation.env]
+    MANTID_BUILD_DIR = "/absolute/path/to/your/mantid/build"
+    MANTID_SOURCE_DIR = "/absolute/path/to/your/mantid/source"
+    PYTHONPATH = "${MANTID_BUILD_DIR}/bin:${MANTID_SOURCE_DIR}/Framework/PythonInterface:${MANTID_SOURCE_DIR}/qt/python/mantidqt"
+    LD_LIBRARY_PATH = "${MANTID_BUILD_DIR}/bin"        # Linux
+    DYLD_LIBRARY_PATH = "${MANTID_BUILD_DIR}/bin"      # macOS
+    MANTIDPATH = "${MANTID_BUILD_DIR}/bin"
+
+    [tool.pixi.feature.local-mantid.tasks]
+    # Launch local Mantid Workbench with your application
+    launch-local-workbench = { cmd = "cd $MANTID_BUILD_DIR/bin && ./launch_mantidworkbench.sh", description = "Launch local Mantid Workbench with your application available" }
+
+Replace the paths with your actual Mantid build and source directories.
+
+Usage
+#####
+
+1. Install the environment:
+
+   .. code-block:: bash
+
+       pixi install --environment local-mantid
+
+2. Run your application:
+
+   .. code-block:: bash
+
+       pixi run --environment local-mantid your-command
+
+3. Run Local Workbench in your application's context:
+
+   .. code-block:: bash
+
+       pixi run --environment local-mantid launch-local-workbench
+
+Troubleshooting
+###############
+
+**Import errors**: Verify ``PYTHONPATH`` includes ``${MANTID_BUILD_DIR}/bin`` and your Mantid build completed successfully.
+
+**Library loading errors**: Check that ``LD_LIBRARY_PATH`` (Linux) or ``DYLD_LIBRARY_PATH`` (macOS) includes ``${MANTID_BUILD_DIR}/bin``.
+
+**Path issues**: Ensure all paths are absolute. Use ``realpath`` to resolve symbolic links if needed.
+
+You can verify the environment setup with:
+
+.. code-block:: bash
+
+    pixi run --environment local-mantid python -c "
+    import os, mantid
+    print('Mantid version:', mantid.__version__)
+    print('Mantid path:', mantid.__file__)
+    print('Build dir:', os.environ.get('MANTID_BUILD_DIR'))
+    "
+
+Related Documentation
+#####################
+
+* :ref:`BuildingWithCMake` - Building Mantid from source
+* :ref:`GettingStarted` - Initial setup for Mantid development
+* `Pixi Documentation <https://pixi.ws/latest/>`_ - Complete pixi reference

dev-docs/source/index.rst

@@ -20,6 +20,7 @@ Guides
    Architecture
    BuildingOnOSX
    BuildingWithCMake
+   LocalMantidBuildWithPixi
    CMakeBestPractices
    Standards/index
    Testing/index
@@ -40,6 +41,9 @@ Guides
 :doc:`Architecture`
    Describes the architecture of the mantid libraries and applications.
 
+:doc:`LocalMantidBuildWithPixi`
+   How to set up a pixi environment to use a local Mantid build instead of conda packages in other projects.
+
 :doc:`Standards <Standards/index>`
    Details of coding and documentation standards for the project. Includes specifics regarding algorithms.