diff --git a/.gitignore b/.gitignore
index 15c86627d..6599779e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,4 @@ freud/*.cpp
freud/*.cxx
freud/*.dylib
freud/*.so
+html
diff --git a/doc/source/gettingstarted/installation.rst b/doc/source/gettingstarted/installation.rst
index f8d0faba9..248a01f9a 100644
--- a/doc/source/gettingstarted/installation.rst
+++ b/doc/source/gettingstarted/installation.rst
@@ -1,36 +1,40 @@
.. _installation:
-============
Installation
============
-Installing freud
-================
-
**freud** binaries are available on conda-forge_ and PyPI_. You can also compile **freud** from
source.
-Install via conda
------------------
+Binaries
+--------
+
+conda-forge package
+^^^^^^^^^^^^^^^^^^^
**freud** is available on conda-forge_ for the *linux-64*, *osx-64*, *osx-arm64* and *win-64*
-architectures. Install with:
+architectures. Execute one of the following commands to install **freud**:
-.. code:: bash
+.. code-block:: bash
+
+ micromamba install freud
+
+**OR**
+
+.. code-block:: bash
mamba install freud
-Install via pip
------------------
+PyPI
+^^^^
-To install **freud** is also available from PyPI_. To install **freud** into a *non-conda* virtual
-environment, execute:
+Use **uv** or **pip** to install **freud** binaries from PyPI_ into a virtual environment:
.. code:: bash
uv pip install freud-analysis
-or
+**OR**
.. code:: bash
@@ -42,147 +46,211 @@ or
Compile from source
-------------------
-The following are **required** for building and installing **freud** from source:
+To build **freud** from source:
-- A C++17-compliant compiler
-- `Python `__ (>=3.9)
-- `NumPy `__ (>=1.19)
-- `Intel Threading Building Blocks `__ (>=2019.7)
-- `Cython `__ (>=3.0.2)
-- `scikit-build `__ (>=0.10.0)
-- `CMake `__ (>=3.13.0)
+1. `Obtain the source`_:
-.. note::
+ .. code-block:: bash
- Depending on the generator you are using, you may require a newer version of CMake.
- In particular, Visual Studio 2019 requires CMake >= 3.14.0.
- For more information on specific generators, see the `CMake generator documentation `__.
+ git clone --recursive git@github.com:glotzerlab/freud.git
-The **freud** library uses scikit-build and CMake to handle the build process itself, while the other requirements are required for compiling code in **freud**.
-These requirements can be met by installing the following packages from the `conda-forge channel `__:
+2. Change to the repository directory::
-.. code-block:: bash
+ cd freud
- mamba install conda-forge tbb tbb-devel numpy cython scikit-build cmake
+3. `Install with uv`_::
-All requirements other than TBB can also be installed via the `Python Package Index `__
+ uv pip install .
-.. code-block:: bash
+4. **OR** `Install prerequisites`_ and `Build with CMake for development`_:
- uv pip install numpy cython scikit-build cmake
+ .. code-block:: bash
-Wheels for tbb and tbb-devel exist on PyPI, but only for certain operating systems, so your mileage may vary.
-For non-conda users, we recommend using OS-specific package managers (e.g. `Homebrew `__ for Mac) to install TBB.
-As in the snippets above, it may be necessary to install both both a TBB and a "devel" package in order to get both the headers and the shared libraries.
+ micromamba install cmake ninja numpy python tbb-devel nanobind scikit-build-core gsd matplotlib pytest rowan scipy sympy
-The code that follows builds **freud** and installs it for all users (append ``--user`` if you wish to install it to your user site directory):
+ .. code-block:: bash
+
+ cmake -B build -S . -GNinja
+ cd build
+ ninja
-.. code-block:: bash
+To run the tests:
- git clone --recurse-submodules https://github.com/glotzerlab/freud.git
- cd freud
- uv pip install .
+1. `Run tests`_::
-CMake Options
-+++++++++++++
+ cd tests
+ PYTHONPATH=../build python3 -m pytest
-The scikit-build tool allows setup.py to accept three different sets of options separated by ``--``, where each set is provided directly to scikit-build, to CMake, or to the code generator of choice, respectively.
-For example, the command ``python setup.py build_ext --inplace -- -DCOVERAGE=ON -G Ninja -- -j 4`` tell scikit-build to perform an in-place build, it tells CMake to turn on the ``COVERAGE`` option and use Ninja for compilation, and it tells Ninja to compile with 4 parallel threads.
-For more information on these options, see the `scikit-build docs `__.
+To build the documentation from source:
-In addition to standard CMake flags, the following CMake options are available for **freud**:
+1. `Install prerequisites`_::
-.. glossary::
+ micromamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton
- \--COVERAGE
- Build the Cython files with coverage support to check unit test coverage.
+2. `Build the documentation`_:
+ .. code-block:: bash
-The **freud** CMake configuration also respects the following environment variables (in addition to standards like ``CMAKE_PREFIX_PATH``).
+ cd {{ path/to/freud/repository }}
+
+ .. code-block:: bash
-.. glossary::
+ sphinx-build -b html doc html
- TBBROOT
- The root directory where TBB is installed.
- Useful if TBB is installed in a non-standard location or cannot be located for some other reason.
- This variable is set by the ``tbbvars.sh`` script included with TBB when building from source.
+The sections below provide details on each of these steps.
- TBB_INCLUDE_DIR
- The directory where the TBB headers (e.g. ``tbb.h``) are located.
- Useful if TBB is installed in a non-standard location or cannot be located for some other reason.
+.. _Install prerequisites:
-.. note::
+Install prerequisites
+^^^^^^^^^^^^^^^^^^^^^
- **freud** makes use of git submodules. To manually update git submodules, execute:
+**freud** requires a number of tools and libraries to build.
- .. code-block:: bash
+**General requirements:**
- git submodule update --init --recursive
+- A C++17-compliant compiler.
+- **CMake** >= 3.15.0
+- **Intel Threading Building Blocks** >= 2019.7
+- **nanobind** >= 2.0.0
+- **NumPy** >= 1.19.0
+- **Python** >= 3.9
+- **scikit-build-core**
-Unit Tests
-==========
+**To execute unit tests:**
-The unit tests for **freud** are included in the repository and are configured to be run using the Python :mod:`pytest` library:
+- **dynasor** (optional)
+- **gsd**
+- **matplotlib**
+- **pytest**
+- **rowan**
+- **scipy**
+- **sympy**
+
+.. _Obtain the source:
+
+Obtain the source
+^^^^^^^^^^^^^^^^^
+
+Clone using Git_:
.. code-block:: bash
- # Run tests from the tests directory
- cd tests
- python -m pytest .
+ git clone --recursive git@github.com:glotzerlab/freud.git
+
+Release tarballs are also available on the `GitHub release pages`_.
+
+.. seealso::
+
+ See the `git book`_ to learn how to work with `Git`_ repositories.
+
+.. _GitHub release pages: https://github.com/glotzerlab/freud/releases/
+.. _git book: https://git-scm.com/book
+.. _Git: https://git-scm.com/
+
+
+.. _Install with uv:
+
+Install with uv
+^^^^^^^^^^^^^^^^
-Note that because **freud** is designed to require installation to run (i.e. it cannot be run directly out of the build directory), importing **freud** from the root of the repository will fail because it will try and import the package folder.
-As a result, unit tests must be run from outside the root directory if you wish to test the installed version of **freud**.
-If you want to run tests within the root directory, you can instead build **freud** in place:
+Use **uv** to install the Python module into your virtual environment:
.. code-block:: bash
- # Run tests from the tests directory
- python setup.py build_ext --inplace
+ cd {{ path/to/freud/repository }}
-This build will place the necessary files alongside the **freud** source files so that **freud** can be imported from the root of the repository.
+.. code-block:: bash
+
+ uv pip install .
+
+To perform incremental builds, `install the prerequisites first `_, then run:
+
+.. code-block:: bash
+
+ uv pip install --no-deps --no-build-isolation --force-reinstall -C build-dir=$PWD/build .
-Documentation
-=============
+You may find using `CMake`_ directly more effective for incremental builds (see the next section).
-The documentation for **freud** is `hosted online at ReadTheDocs `_.
-You may also build the documentation yourself.
+.. Build with CMake for development:
-Building the documentation
---------------------------
+Build with CMake for development
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The following are **required** for building **freud** documentation:
+**freud** also provides `CMake`_ scripts for development and testing that build a functional Python
+module in the build directory. First, configure the build with ``cmake``:
-- `Sphinx `_
-- `The furo Sphinx Theme `_
-- `nbsphinx `_
-- `jupyter_sphinx `_
-- `sphinxcontrib-bibtex `_
-- `sphinx-copybutton `_
+.. code-block:: bash
-You can install these dependencies using conda:
+ cd {{ path/to/freud/repository }}
.. code-block:: bash
- mamba install sphinx furo nbsphinx jupyter_sphinx sphinxcontrib-bibtex sphinx-copybutton
+ cmake -B build -S . -GNinja
-or pip:
+Then, build the code:
.. code-block:: bash
- uv pip install sphinx sphinx-rtd-theme nbsphinx jupyter-sphinx sphinxcontrib-bibtex sphinx-copybutton
+ cd build
+ ninja
+
+Execute ``ninja`` to rebuild after you modify the code. ``ninja`` will automatically reconfigure
+as needed.
+
+.. tip::
+
+ Pass the following options to ``cmake`` to optimize the build for your processor:
+ ``-DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native``.
+
+.. warning::
+
+ When using a ``conda-forge`` environment for development, make sure that the environment does
+ not contain ``clang``, ``gcc``, or any other compiler or linker. These interfere with the native
+ compilers on your system and will result in compiler errors when building, linker errors when
+ running, or segmentation faults.
+
+.. _CMake: https://cmake.org/
+.. _Ninja: https://ninja-build.org/
+
+
+Run tests
+^^^^^^^^^
+
+.. note::
+
+ You must first `Obtain the source`_ before you can run the tests.
+
+Use `pytest`_ to execute unit tests:
+
+.. code-block:: bash
-To build the documentation, run the following commands in the source directory:
+ cd {{ path/to/freud/repository }}
+ cd tests
.. code-block:: bash
- cd doc
- make html
- # Then open build/html/index.html
+ PYTHONPATH=../build python3 -m pytest
+
+.. _pytest: https://docs.pytest.org/
+
-To build a PDF of the documentation (requires LaTeX and/or PDFLaTeX):
+.. _Build the documentation:
+
+Build the documentation
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Run `Sphinx`_ to build the HTML documentation:
.. code-block:: bash
- cd doc
- make latexpdf
- # Then open build/latex/freud.pdf
+ PYTHONPATH=build sphinx-build -b html doc/source html
+
+Open the file :file:`html/index.html` in your web browser to view the documentation.
+
+.. tip::
+
+ Add the sphinx options ``-a -n -W -T --keep-going`` to produce docs with consistent links in
+ the side panel and provide more useful error messages.
+
+.. _Sphinx: https://www.sphinx-doc.org/
+