Revise installation documentation.

.gitignore

@@ -22,3 +22,4 @@ freud/*.cpp
 freud/*.cxx
 freud/*.dylib
 freud/*.so
+html

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 <https://www.python.org/>`__ (>=3.9)
-- `NumPy <https://www.numpy.org/>`__ (>=1.19)
-- `Intel Threading Building Blocks <https://www.threadingbuildingblocks.org/>`__ (>=2019.7)
-- `Cython <https://cython.org/>`__ (>=3.0.2)
-- `scikit-build <https://scikit-build.readthedocs.io/>`__ (>=0.10.0)
-- `CMake <https://cmake.org/>`__ (>=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 <https://cmake.org/cmake/help/git-stage/manual/cmake-generators.7.html>`__.
+      git clone --recursive [email protected]: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 <https://conda-forge.org/>`__:
+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 <https://pypi.org/>`__
+    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 <https://brew.sh/>`__ 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 <https://scikit-build.readthedocs.io/>`__.
+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 [email protected]: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 <Install prerequisites>`_, 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 <https://freud.readthedocs.io/>`_.
-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 <http://www.sphinx-doc.org/>`_
-- `The furo Sphinx Theme <https://pradyunsg.me/furo/>`_
-- `nbsphinx <https://nbsphinx.readthedocs.io/>`_
-- `jupyter_sphinx <https://jupyter-sphinx.readthedocs.io/>`_
-- `sphinxcontrib-bibtex <https://sphinxcontrib-bibtex.readthedocs.io/>`_
-- `sphinx-copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`_
+.. 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/
+