Create docs and update some doc strings

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,79 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+# -- Path Info ---------------------------------------------------------------
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../'))
+# sys.path.insert(0, os.path.abspath('../../'))
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'DPM_Tools'
+copyright = '2024, Digital Porous Media Team'
+author = 'Digital Porous Media Team'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',
+    'sphinx_copybutton',
+    'sphinx_design',
+    'myst_nb',
+]
+
+add_module_names = False  # dpm_tools.visualization -> visualization
+autosummary_generate = True
+globaltoc_maxdepth = 2
+
+templates_path = ['_templates']
+master_doc = 'index'
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+# A list of ignored prefixes for module index sorting.
+modindex_common_prefix = ['dpm_tools']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'karma_sphinx_theme'
+html_static_path = ['_static']
+html_domain_indices = True
+html_use_index = True
+html_split_index = False
+#
+# html_theme_options = {
+#     "icon_links": [
+#         {
+#             "name": "GitHub",
+#             "url": "https://github.com/digital-porous-media/dpm_tools",
+#             "icon": "fab fa-github-square",
+#         },
+#     ],
+#     "external_links": [
+#         {
+#             "name": "Issue Tracker", "url": "https://github.com/digital-porous-media/dpm_tools/issues"
+#         },
+#         {
+#             "name": "Get Help", "url": "https://github.com/digital-porous-media/dpm_tools/discussions"
+#         },
+#     ],
+#     "navigation_with_keys": False,
+#     "show_prev_next": False,
+#     "icon_links_label": "Quick Links",
+#     "use_edit_page_button": False,
+#     "search_bar_position": "sidebar",
+#     "navbar_align": "left",
+# }

docs/dpm_tools.io.rst

@@ -0,0 +1,37 @@
+dpm\_tools.io package
+=====================
+
+Submodules
+----------
+
+dpm\_tools.io.io\_utils module
+------------------------------
+
+.. automodule:: dpm_tools.io.io_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dpm\_tools.io.read\_data module
+-------------------------------
+
+.. automodule:: dpm_tools.io.read_data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dpm\_tools.io.write\_data module
+--------------------------------
+
+.. automodule:: dpm_tools.io.write_data
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: dpm_tools.io
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/dpm_tools.morphology.rst

@@ -0,0 +1,21 @@
+dpm\_tools.morphology package
+=============================
+
+Submodules
+----------
+
+dpm\_tools.morphology.features module
+-------------------------------------
+
+.. automodule:: dpm_tools.morphology.features
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: dpm_tools.morphology
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/dpm_tools.rst

@@ -0,0 +1,20 @@
+dpm\_tools package
+==================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   dpm_tools.io
+   dpm_tools.morphology
+   dpm_tools.visualization
+
+Module contents
+---------------
+
+.. automodule:: dpm_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/dpm_tools.visualization.rst

@@ -0,0 +1,29 @@
+dpm\_tools.visualization package
+================================
+
+Submodules
+----------
+
+dpm\_tools.visualization.plot\_2d module
+----------------------------------------
+
+.. automodule:: dpm_tools.visualization.plot_2d
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+dpm\_tools.visualization.plot\_3d module
+----------------------------------------
+
+.. automodule:: dpm_tools.visualization.plot_3d
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: dpm_tools.visualization
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/index.rst

@@ -0,0 +1,21 @@
+.. DPM_Tools documentation master file, created by
+   sphinx-quickstart on Mon Feb 19 10:35:17 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to DPM_Tools's documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules.rst

@@ -0,0 +1,7 @@
+dpm_tools
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   dpm_tools

dpm_tools/__init__.py

@@ -1,7 +1,9 @@
-# import io
-# import visualization
 from time import perf_counter_ns
 
+from . import morphology
+from . import io
+from . import visualization
+
 def _get_version():
     from .__version__ import __version__
     suffix = "dev"

dpm_tools/io/__init__.py

@@ -1,13 +1,5 @@
-# from .io_utils import _find_files
-# from .io_utils import _find_tiff_files
-# from .io_utils import _evaluate_dimensions
-# from .io_utils import _sort_files
-# from .io_utils import _combine_slices
-from .io_utils import convert_filetype
+from .io_utils import *
 
-from .read_data import read_image
-from .read_data import Image
-from .read_data import ImageFromFile
-from .read_data import Vector
+from .read_data import *
 
-from .write_data import write_image
+from .write_data import *

dpm_tools/io/read_data.py

@@ -7,6 +7,12 @@
 from dataclasses import dataclass, field
 from collections.abc import Iterable
 
+# __all__ = [
+#     'read_image',
+#     'ImageFromFile',
+#     'Image',
+#     'Vector'
+# ]
 def _read_tiff(filepath: str, full_path: bool = True, **kwargs) -> np.ndarray:
     """
     A utility function to read in TIFF files

dpm_tools/morphology/__init__.py

@@ -1,9 +1,4 @@
-from .features import edt
-from .features import slicewise_edt
-from .features import slicewise_mis
-from .features import chords
-from .features import constriction_factor
-from .features import tof
+from .features import *
 
-from ._feature_utils import _get_trend
+from ._feature_utils import *
 

dpm_tools/morphology/_feature_utils.py

@@ -1,26 +1,32 @@
 import numpy as np
 
+__all__ = ['_set_linear_trend']
 
-def _get_trend(data, inlet_value: float = 2, outlet_value: float = 1, grid_shift: bool = True) -> np.ndarray:
+
+def _set_linear_trend(data, inlet_value: float = 2, outlet_value: float = 1, grid_shift: bool = True) -> np.ndarray:
     """
-    Get a linear trend through the domain
-    Assumes grain voxels are 0
+    Set a linear trend through the foreground of a 3D image. Phases labeled 0 will be masked out.
+    :param data: Image dataclass
+    :param inlet_value: Value to set at the inlet
+    :param outlet_value: Value to set at the outlet
+    :param grid_shift: If True, shift the inlet and outlet values by 1/nz
+    :return: Linear trend through foreground of the image
+    :rtype: numpy.ndarray
     """
     linear = np.zeros_like(data.image, dtype=np.float32)
 
     if grid_shift:
-        inlet_value = 2 - 1/data.nz
-        outlet_value = 1 - 1/data.nz
+        inlet_value = 2 - 1 / data.nz
+        outlet_value = 1 - 1 / data.nz
 
     tmp = np.linspace(inlet_value, outlet_value, data.nz)
 
     linear = np.broadcast_to(tmp, data.image.shape)
-    #for tmp_slice, i in enumerate(tmp):
+    # for tmp_slice, i in enumerate(tmp):
     #    linear[:, :, tmp_slice] = np.ones((data.nx, data.ny)) * i
 
     mask = (data.img != 0)
 
     linear = linear * mask
 
     return linear
-