Update installation guide, better describe installation of nlopt

Signed-off-by: Håkon Wiik Ånes <[email protected]>

doc/dev/building_writing_documentation.rst

@@ -10,7 +10,7 @@ New documents should fit into one of these categories.
 We use :doc:`Sphinx <sphinx:index>` for documenting functionality.
 Install necessary dependencies to build the documentation::
 
-    pip install --editable .[doc]
+    pip install --editable ".[doc]"
 
 .. note::
 
@@ -24,11 +24,11 @@ Then, build the documentation from the ``doc`` directory::
     cd doc
     make html
 
-The documentation's HTML pages are built in the ``doc/build/html`` directory from files
+The documentation's HTML pages are built in the ``doc/_build/html`` directory from files
 in the :doc:`reStructuredText (reST) <sphinx:usage/restructuredtext/basics>` plaintext
 markup language.
 They should be accessible in the browser by typing
-``file:///your/absolute/path/to/kikuchipy/doc/build/html/index.html`` in the address
+``file:///your/absolute/path/to/kikuchipy/doc/_build/html/index.html`` in the address
 bar.
 
 We can link to other documentation in reStructuredText files using

doc/dev/running_writing_tests.rst

@@ -22,7 +22,7 @@ corresponding background pattern, are available in the ``conftest.py`` file.
 
 To run the tests::
 
-    pytest --cov --pyargs kikuchipy
+    pytest --cov
 
 The ``--cov`` flag makes :doc:`coverage.py <coverage:index>` print a nice report in the
 terminal.
@@ -53,7 +53,7 @@ failing results without code changes) using the pytest plugin pytest-rerunfailur
 Docstring examples are tested :doc:`with pytest <pytest:how-to/doctest>` as well.
 If you're in the top directory you can run::
 
-    pytest --doctest-modules --ignore-glob=kikuchipy/*/tests kikuchipy/*.py
+    pytest --doctest-modules src
 
 Functionality using Numba
 -------------------------

doc/dev/setting_up_development_installation.rst

@@ -27,7 +27,9 @@ with the `Miniconda distribution <https://docs.conda.io/en/latest/miniconda.html
 Then, install the required dependencies while making the development version available
 globally (in the ``conda`` environment)::
 
-    pip install --editable .[dev]
+    pip install --editable ".[dev]"
 
 This installs all necessary development dependencies, including those for running tests
-and building documentation.
+and building documentation.
+Further details are available in the :ref:`dependencies` section of the installation
+guide.

doc/user/installation.rst

@@ -4,7 +4,7 @@ Installation
 
 kikuchipy can be installed with `pip <https://pypi.org/project/kikuchipy/>`__,
 `conda <https://anaconda.org/conda-forge/kikuchipy>`__, the
-:ref:`hyperspy:hyperspy-bundle`, or from source, and supports Python >= 3.7.
+:ref:`hyperspy:hyperspy-bundle`, or from source, and supports Python >= 3.8.
 All alternatives are available on Windows, macOS and Linux.
 
 .. _install-with-pip:
@@ -26,29 +26,6 @@ To install a specific version of kikuchipy (say version 0.8.5)::
 
     pip install kikuchipy==0.8.5
 
-.. _optional-dependencies:
-
-Optional dependencies
----------------------
-
-Some functionality is optional and requires extra dependencies which must be installed
-manually:
-
-- :doc:`pyebsdindex<pyebsdindex:index>`: Hough indexing. We recommend to install with
-  optional GPU support via :doc:`pyopencl<pyopencl:index>` with
-  ``pip install pyebsdindex[gpu]`` or ``conda install pyebsdindex``.
-- `nlopt <https://nlopt.readthedocs.io/en/latest/NLopt_Python_Reference/>`_: Extra
-  optimization algorithms used in EBSD orientation and/or projection center refinement.
-- :doc:`pyvista<pyvista:index>`: 3D plotting of master patterns.
-
-Install all optional dependencies::
-
-    pip install kikuchipy[all]
-
-Note that this command will not install ``pyopencl``, which is required for GPU support
-in ``pyebsdindex``. If the above command failed for some reason, one can try to install
-each optional dependency individually.
-
 .. _install-with-anaconda:
 
 With Anaconda
@@ -59,7 +36,7 @@ To install with Anaconda, we recommend you install it in a
 `Miniconda distribution <https://docs.conda.io/en/latest/miniconda.html>`__.
 To create an environment and activate it, run the following::
 
-   conda create --name kp-env python=3.11
+   conda create --name kp-env python=3.12
    conda activate kp-env
 
 If you prefer a graphical interface to manage packages and environments, you can install
@@ -107,29 +84,47 @@ To install kikuchipy from source, clone the repository from `GitHub
 See the contributing guide for :ref:`setting-up-a-development-installation` and keeping
 it up to date.
 
+.. _dependencies:
+
 Dependencies
 ============
 
 kikuchipy builds on the great work and effort of many people.
-This is a list of explicit package dependencies (some are `Optional dependencies`_):
-
-==================================================== ============================================================
-Package                                              Purpose
-==================================================== ============================================================
-:doc:`dask<dask:index>`                              Out-of-memory processing of data larger than RAM
-:doc:`diffpy.structure <diffpy.structure:index>`     Handling of crystal structures
-:doc:`diffsims <diffsims:index>`                     Handling of reciprocal lattice vectors and structure factors
-:doc:`hyperspy <hyperspy:index>`                     Multi-dimensional data handling (EBSD class etc.)
-:doc:`h5py <h5py:index>`                             Read/write of HDF5 files
-:doc:`imageio <imageio:index>`                       Read image formats
-:doc:`matplotlib <matplotlib:index>`                 Visualization
-:doc:`numba <numba:index>`                           CPU acceleration
-:doc:`numpy <numpy:index>`                           Handling of N-dimensional arrays
-:doc:`orix <orix:index>`                             Handling of rotations and vectors using crystal symmetry
-:doc:`pooch <pooch:api/index>`                       Downloading and caching of datasets
-`pyyaml <https://pyyaml.org/>`__                     Parcing of YAML files
-`tqdm <https://tqdm.github.io/>`__                   Progressbars
-:doc:`scikit-image <skimage:index>`                  Image processing like adaptive histogram equalization
-`scikit-learn <https://scikit-learn.org/stable/>`__  Multivariate analysis
-:doc:`scipy <scipy:index>`                           Optimization algorithms, filtering and more
-==================================================== ============================================================
+This is a list of core package dependencies:
+
+* :doc:`dask<dask:index>`: Out-of-memory processing of data larger than RAM
+* :doc:`diffpy.structure <diffpy.structure:index>`: Handling of crystal structures
+* :doc:`diffsims <diffsims:index>`: Handling of reciprocal lattice vectors and structure
+  factors
+* :doc:`hyperspy <hyperspy:index>`: Multi-dimensional data handling (EBSD class etc.)
+* :doc:`h5py <h5py:index>`: Read/write of HDF5 files
+* :doc:`imageio <imageio:index>`: Read image formats
+* :doc:`matplotlib <matplotlib:index>`: Visualization
+* :doc:`numba <numba:index>`: CPU acceleration via just-in-time compilation
+* :doc:`numpy <numpy:index>`: Handling of N-dimensional arrays
+* :doc:`orix <orix:index>`: Handling of rotations and vectors using crystal symmetry
+* :doc:`pooch <pooch:api/index>`: Downloading and caching of datasets
+* `pyyaml <https://pyyaml.org/>`__: Parcing of YAML files
+* `tqdm <https://tqdm.github.io/>`__: Progressbars
+* :doc:`scikit-image <skimage:index>`: Image processing like adaptive histogram
+  equalization
+* `scikit-learn <https://scikit-learn.org/stable/>`__: Multivariate analysis
+* :doc:`scipy <scipy:index>`: Optimization algorithms, filtering and more
+
+Some functionality requires optional dependencies:
+
+* :doc:`pyebsdindex <pyebsdindex:index>`: Hough indexing. We recommend to install with
+  optional GPU support via :doc:`pyopencl<pyopencl:index>` with
+  ``pip install "pyebsdindex[gpu]""`` or ``conda install pyebsdindex -c conda-forge``.
+* `nlopt <https://nlopt.readthedocs.io/en/latest/NLopt_Python_Reference/>`__: Extra
+  optimization algorithms used in EBSD orientation and/or projection center refinement.
+  Installation from conda ``conda install nlopt -c conda-forge`` is recommended.
+* :doc:`pyvista<pyvista:index>`: 3D plotting of master patterns.
+
+Install all optional dependencies::
+
+    pip install "kikuchipy[all]"
+
+Note that this command will not install ``pyopencl``, which is required for GPU support
+in ``pyebsdindex``. If the above command failed for some reason, you can try to install
+each optional dependency individually.

src/kikuchipy/detectors/ebsd_detector.py

@@ -1161,8 +1161,7 @@ def get_indexer(
         Notes
         -----
         Requires that PyEBSDIndex is installed, which is an optional
-        dependency of kikuchipy. See :ref:`optional-dependencies` for
-        details.
+        dependency of kikuchipy. See :ref:`dependencies` for details.
 
         See Also
         --------

src/kikuchipy/indexing/_hough_indexing.py

@@ -156,8 +156,7 @@ def _get_indexer_from_detector(
     Notes
     -----
     Requires that :mod:`pyebsdindex` is installed, which is an optional
-    dependency of kikuchipy. See :ref:`optional-dependencies` for
-    details.
+    dependency of kikuchipy. See :ref:`dependencies` for details.
     """
     if not _pyebsdindex_installed:  # pragma: no cover
         raise ValueError(

src/kikuchipy/signals/_kikuchi_master_pattern.py

@@ -246,7 +246,7 @@ def plot_spherical(
         Notes
         -----
         Requires :mod:`pyvista` (see :ref:`the installation guide
-        <optional-dependencies>`).
+        <dependencies>`).
 
         Examples
         --------

src/kikuchipy/signals/ebsd.py

@@ -1646,7 +1646,7 @@ def hough_indexing(
         Notes
         -----
         Requires :mod:`pyebsdindex` to be installed. See
-        :ref:`optional-dependencies` for further details.
+        :ref:`dependencies` for further details.
 
         This wrapper of PyEBSDIndex is meant for convenience more than
         speed. It uses the GPU if :mod:`pyopencl` is installed, but only
@@ -1749,7 +1749,7 @@ def hough_indexing_optimize_pc(
         Notes
         -----
         Requires :mod:`pyebsdindex` to be installed. See
-        :ref:`optional-dependencies` for further details.
+        :ref:`dependencies` for further details.
         """
         if not _pyebsdindex_installed:  # pragma: no cover
             raise ValueError(
@@ -2136,7 +2136,7 @@ def refine_orientation(
         Notes
         -----
         *NLopt* is for now an optional dependency, see
-        :ref:`optional-dependencies` for details. Be aware that *NLopt*
+        :ref:`dependencies` for details. Be aware that *NLopt*
         does not fail gracefully. If continued use of *NLopt* proves
         stable enough, its implementation of the Nelder-Mead algorithm
         might become the default.
@@ -2326,7 +2326,7 @@ def refine_projection_center(
         shape.
 
         *NLopt* is for now an optional dependency, see
-        :ref:`optional-dependencies` for details. Be aware that *NLopt*
+        :ref:`dependencies` for details. Be aware that *NLopt*
         does not fail gracefully. If continued use of *NLopt* proves
         stable enough, its implementation of the Nelder-Mead algorithm
         might become the default.
@@ -2543,7 +2543,7 @@ def refine_orientation_projection_center(
         the output is reasonable.
 
         *NLopt* is for now an optional dependency, see
-        :ref:`optional-dependencies` for details. Be aware that *NLopt*
+        :ref:`dependencies` for details. Be aware that *NLopt*
         does not fail gracefully. If continued use of *NLopt* proves
         stable enough, its implementation of the Nelder-Mead algorithm
         might become the default.