diff --git a/doc/dev/building_writing_documentation.rst b/doc/dev/building_writing_documentation.rst index 27cb2f1d..2764a04f 100644 --- a/doc/dev/building_writing_documentation.rst +++ b/doc/dev/building_writing_documentation.rst @@ -10,7 +10,7 @@ New documents should fit into one of these categories. We use :doc:`Sphinx ` 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) ` 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 diff --git a/doc/dev/running_writing_tests.rst b/doc/dev/running_writing_tests.rst index 8f35ba01..b4ffb25d 100644 --- a/doc/dev/running_writing_tests.rst +++ b/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 ` 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 ` 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 ------------------------- diff --git a/doc/dev/setting_up_development_installation.rst b/doc/dev/setting_up_development_installation.rst index b1647b86..12ef05f9 100644 --- a/doc/dev/setting_up_development_installation.rst +++ b/doc/dev/setting_up_development_installation.rst @@ -27,7 +27,9 @@ with the `Miniconda distribution `__, `conda `__, 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`: Hough indexing. We recommend to install with - optional GPU support via :doc:`pyopencl` with - ``pip install pyebsdindex[gpu]`` or ``conda install pyebsdindex``. -- `nlopt `_: Extra - optimization algorithms used in EBSD orientation and/or projection center refinement. -- :doc:`pyvista`: 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 `__. 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` Out-of-memory processing of data larger than RAM -:doc:`diffpy.structure ` Handling of crystal structures -:doc:`diffsims ` Handling of reciprocal lattice vectors and structure factors -:doc:`hyperspy ` Multi-dimensional data handling (EBSD class etc.) -:doc:`h5py ` Read/write of HDF5 files -:doc:`imageio ` Read image formats -:doc:`matplotlib ` Visualization -:doc:`numba ` CPU acceleration -:doc:`numpy ` Handling of N-dimensional arrays -:doc:`orix ` Handling of rotations and vectors using crystal symmetry -:doc:`pooch ` Downloading and caching of datasets -`pyyaml `__ Parcing of YAML files -`tqdm `__ Progressbars -:doc:`scikit-image ` Image processing like adaptive histogram equalization -`scikit-learn `__ Multivariate analysis -:doc:`scipy ` Optimization algorithms, filtering and more -==================================================== ============================================================ +This is a list of core package dependencies: + +* :doc:`dask`: Out-of-memory processing of data larger than RAM +* :doc:`diffpy.structure `: Handling of crystal structures +* :doc:`diffsims `: Handling of reciprocal lattice vectors and structure + factors +* :doc:`hyperspy `: Multi-dimensional data handling (EBSD class etc.) +* :doc:`h5py `: Read/write of HDF5 files +* :doc:`imageio `: Read image formats +* :doc:`matplotlib `: Visualization +* :doc:`numba `: CPU acceleration via just-in-time compilation +* :doc:`numpy `: Handling of N-dimensional arrays +* :doc:`orix `: Handling of rotations and vectors using crystal symmetry +* :doc:`pooch `: Downloading and caching of datasets +* `pyyaml `__: Parcing of YAML files +* `tqdm `__: Progressbars +* :doc:`scikit-image `: Image processing like adaptive histogram + equalization +* `scikit-learn `__: Multivariate analysis +* :doc:`scipy `: Optimization algorithms, filtering and more + +Some functionality requires optional dependencies: + +* :doc:`pyebsdindex `: Hough indexing. We recommend to install with + optional GPU support via :doc:`pyopencl` with + ``pip install "pyebsdindex[gpu]""`` or ``conda install pyebsdindex -c conda-forge``. +* `nlopt `__: 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`: 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. diff --git a/src/kikuchipy/detectors/ebsd_detector.py b/src/kikuchipy/detectors/ebsd_detector.py index a1871170..9be61fde 100644 --- a/src/kikuchipy/detectors/ebsd_detector.py +++ b/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 -------- diff --git a/src/kikuchipy/indexing/_hough_indexing.py b/src/kikuchipy/indexing/_hough_indexing.py index 958dfb8b..2bd2340d 100644 --- a/src/kikuchipy/indexing/_hough_indexing.py +++ b/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( diff --git a/src/kikuchipy/signals/_kikuchi_master_pattern.py b/src/kikuchipy/signals/_kikuchi_master_pattern.py index 3a7f1d14..c489dd82 100644 --- a/src/kikuchipy/signals/_kikuchi_master_pattern.py +++ b/src/kikuchipy/signals/_kikuchi_master_pattern.py @@ -246,7 +246,7 @@ def plot_spherical( Notes ----- Requires :mod:`pyvista` (see :ref:`the installation guide - `). + `). Examples -------- diff --git a/src/kikuchipy/signals/ebsd.py b/src/kikuchipy/signals/ebsd.py index 88f95069..47dc4bbe 100644 --- a/src/kikuchipy/signals/ebsd.py +++ b/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.