diff --git a/.github/workflows/httomo_docs.yml b/.github/workflows/httomo_docs.yml index 3620bfb06..4bda85575 100644 --- a/.github/workflows/httomo_docs.yml +++ b/.github/workflows/httomo_docs.yml @@ -31,10 +31,7 @@ jobs: activate-environment: httomo-docs environment-file: ./docs/source/doc-conda-requirements.yml - - name: Build api docs - run: sphinx-apidoc -feT -t=./docs/source/_templates -o ./docs/source/api ./httomo - - - name: Build html + - name: Build docs run: sphinx-build -a -E -b html ./docs/source/ ./docs/build/ - name: Publish docs diff --git a/.gitignore b/.gitignore index 0e5c67a38..5701967cc 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,5 @@ output_dir/ temp.yaml cufile.log +# Sphinx generated API docs +docs/source/developers/generated/ diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..660caa5be --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,32 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + + {% block methods %} + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + {% if item not in inherited_members %} + ~{{ name }}.{{ item }} + {% endif %} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + {% if item not in inherited_members %} + ~{{ name }}.{{ item }} + {% endif %} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 000000000..1516f105a --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,36 @@ +{{ fullname | escape | underline}} + +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ fullname }}.{{ item }} +{%- endfor %} +{% endif %} + +{% if classes %} +.. currentmodule:: {{ fullname }} +.. rubric:: {{ _('Classes') }} + +.. autosummary:: + :toctree: +{% for item in classes %} + {{ item }} +{%- endfor %} +{% endif %} + +{% if functions %} +.. currentmodule:: {{ fullname }} +.. rubric:: {{ _('Functions') }} + +.. autosummary:: + :toctree: +{% for item in functions %} + {{ item }} +{%- endfor %} +{% endif %} + +.. automodule:: {{ fullname }} diff --git a/docs/source/_templates/module.rst_t b/docs/source/_templates/module.rst_t deleted file mode 100644 index bd7adc13a..000000000 --- a/docs/source/_templates/module.rst_t +++ /dev/null @@ -1,7 +0,0 @@ -{%- if show_headings %}:mod:`{{ basename }}` -============================================ -{%- endif %} -.. automodule:: {{ qualname }} -{%- for option in automodule_options %} - :{{ option }}: -{%- endfor %} diff --git a/docs/source/conf.py b/docs/source/conf.py index c0ef590be..e7cb07a6e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,7 +23,6 @@ import os import sys from datetime import date -from unittest import mock # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -33,44 +32,15 @@ # -- Mock imports ------------------------------------------------------------- - -# Mock imports instead of full environment in readthedocs -MOCK_MODULES = [ +autodoc_mock_imports = [ "click", "mpi4py", "cupy", "h5py", - "yaml", - "skimage", - "skimage.exposure", - "nvtx", - "mpi4py.MPI", - "scipy", - "scipy.ndimage", + "hdf5plugin", + "httomo_backends", ] -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = mock.Mock() - - -class CustomMock(mock.Mock): - def __repr__(self): - return "" - - -sys.modules["cupy"] = CustomMock() -sys.modules["numpy"] = CustomMock() -sys.modules["cupyx.scipy.interpolate"] = CustomMock() -sys.modules["cupyx.scipy.ndimage"] = CustomMock() -sys.modules["cupyx.scipy.fft"] = CustomMock() -sys.modules["cupyx.scipy.fftpack"] = CustomMock() -sys.modules["scipy.fftpack"] = CustomMock() -sys.modules["tomobar.methodsDIR_CuPy"] = CustomMock() -sys.modules["tomobar.methodsIR_CuPy "] = CustomMock() -sys.modules["skimage.registration"] = CustomMock() -sys.modules["httomolibgpu.cuda_kernels"] = CustomMock() - - # ------------------------------------------------------------------------------ project = "HTTomo" @@ -109,7 +79,7 @@ def __repr__(self): autosummary_generate = True numfig = True -template_patterns = ["_templates"] +templates_path = ["_templates"] # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" diff --git a/docs/source/developers/api.rst b/docs/source/developers/api.rst new file mode 100644 index 000000000..1a244ab8b --- /dev/null +++ b/docs/source/developers/api.rst @@ -0,0 +1,28 @@ +API +=== + +.. autosummary:: + :recursive: + :toctree: generated + + httomo.base_block + httomo.block_interfaces + httomo.cli + httomo.cli_utils + httomo.darks_flats + httomo.data + httomo.globals + httomo.loaders + httomo.logger + httomo.methods + httomo.method_wrappers + httomo.monitors + httomo.preview + httomo.runner + httomo.sweep_runner + httomo.transform_layer + httomo.transform_loader_params + httomo.types + httomo.ui_layer + httomo.utils + httomo.yaml_checker diff --git a/docs/source/index.rst b/docs/source/index.rst index 9f87d795a..e1fc25491 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -67,3 +67,4 @@ developers/how_to_contribute developers/memory_calculation + developers/api diff --git a/docs/sphinx-build.sh b/docs/sphinx-build.sh index 36a4c8695..051ea1a2f 100644 --- a/docs/sphinx-build.sh +++ b/docs/sphinx-build.sh @@ -10,23 +10,11 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" # members will document all modules # undoc keeps modules without docstrings # show-inheritance displays a list of base classes below the class signature -export SPHINX_APIDOC_OPTIONS='members,show-inheritance,undoc-members' # Remove directory for api so that there are no obsolete files -rm -rf $DIR/source/api/ +rm -rf $DIR/source/generated/ rm -rf $DIR/build/ -# sphinx-apidoc [options] -o [pathnames to exclude] -# -f, --force. Usually, apidoc does not overwrite files, unless this option is given. -# -e, --separate. Put each module file in its own page. -# -T, --no-toc. Do not create a table of contents file. -# -E, --no-headings. Do not create headings for the modules/packages. This is useful, for example, when docstrings already contain headings. -# -t template directory -# add -Q to suppress warnings - -# sphinx-apidoc generates source files that use sphinx.ext.autodoc to document all found modules -sphinx-apidoc -feT -t=$DIR/source/_templates -o $DIR/source/api $DIR/../httomo - # sphinx-build [options] [filenames] # -a Write all output files. The default is to only write output files for new and changed source files. (This may not apply to all builders.) # -E Don’t use a saved environment (the structure caching all cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. diff --git a/httomo/block_interfaces.py b/httomo/block_interfaces.py index 064870777..606252b2b 100644 --- a/httomo/block_interfaces.py +++ b/httomo/block_interfaces.py @@ -1,12 +1,9 @@ -from typing import Literal, Protocol, Tuple, TypeAlias, TypeVar +from typing import Literal, Protocol, Tuple, TypeVar import numpy as np +from httomo.types import generic_array from httomo.runner.auxiliary_data import AuxiliaryData -from httomo.utils import xp - - -generic_array: TypeAlias = np.ndarray | xp.ndarray class BlockTransfer(Protocol): diff --git a/httomo/data/padding.py b/httomo/data/padding.py index 678651814..fe3e28532 100644 --- a/httomo/data/padding.py +++ b/httomo/data/padding.py @@ -1,4 +1,4 @@ -from typing import Optional +from typing import Optional, Union import h5py import numpy as np @@ -10,7 +10,7 @@ def extrapolate_before( - global_data: h5py.Dataset | np.ndarray, + global_data: Union[h5py.Dataset, np.ndarray], block_data: np.ndarray, slices: int, dim: int, @@ -50,7 +50,7 @@ def extrapolate_before( def extrapolate_after( - global_data: h5py.Dataset | np.ndarray, + global_data: Union[h5py.Dataset, np.ndarray], block_data: np.ndarray, slices: int, dim: int, diff --git a/httomo/loaders/standard_tomo_loader.py b/httomo/loaders/standard_tomo_loader.py index eba2a892f..36541eec6 100644 --- a/httomo/loaders/standard_tomo_loader.py +++ b/httomo/loaders/standard_tomo_loader.py @@ -15,6 +15,7 @@ from httomo.runner.dataset import DataSetBlock from httomo.runner.dataset_store_interfaces import DataSetSource from httomo.runner.loader import LoaderInterface +from httomo.types import generic_array from httomo.utils import Pattern, log_once, make_3d_shape_from_shape @@ -88,11 +89,11 @@ def dtype(self) -> np.dtype: return self._data.dtype @property - def flats(self) -> Optional[AuxiliaryData.generic_array]: + def flats(self) -> Optional[generic_array]: return self._aux_data.get_flats() @property - def darks(self) -> Optional[AuxiliaryData.generic_array]: + def darks(self) -> Optional[generic_array]: return self._aux_data.get_darks() @property diff --git a/httomo/runner/auxiliary_data.py b/httomo/runner/auxiliary_data.py index 6dd134af1..edc7782c3 100644 --- a/httomo/runner/auxiliary_data.py +++ b/httomo/runner/auxiliary_data.py @@ -1,6 +1,8 @@ -from typing import Optional, Tuple, Union -from typing_extensions import TypeAlias +from typing import Optional, Tuple + import numpy as np + +from httomo.types import generic_array from httomo.utils import xp, gpu_enabled @@ -12,16 +14,14 @@ class AuxiliaryData: including the GPU/CPU transfers if needed. """ - generic_array: TypeAlias = Union[xp.ndarray, np.ndarray] - def __init__( self, angles: np.ndarray, darks: Optional[np.ndarray] = None, flats: Optional[np.ndarray] = None, ): - self._darks: Optional[AuxiliaryData.generic_array] = darks - self._flats: Optional[AuxiliaryData.generic_array] = flats + self._darks: Optional[generic_array] = darks + self._flats: Optional[generic_array] = flats self._angles: np.ndarray = angles @property diff --git a/httomo/types.py b/httomo/types.py new file mode 100644 index 000000000..25aa7a8ae --- /dev/null +++ b/httomo/types.py @@ -0,0 +1,8 @@ +from typing import TypeAlias, Union + +import numpy as np + +from httomo.utils import xp + + +generic_array: TypeAlias = Union[np.ndarray, xp.ndarray]