From 9a518896016f6df4f4b2052051e7cb70087fb898 Mon Sep 17 00:00:00 2001 From: xPeterS Date: Mon, 13 Jul 2026 13:44:02 -0700 Subject: [PATCH 1/2] Modernize Sphinx docs and fix docstring RST bugs - Auto-generate module .rst stubs with sphinxcontrib.apidoc instead of hand-maintaining them, fixing dead references (ncempy.io.read, ncempy.algo.align/moments/rebin) and adding coverage for modules that had drifted out of the docs (dectris, eels, multicorr, viz.widgets). - Add sphinx.ext.intersphinx mappings (Python, NumPy, SciPy, h5py, Matplotlib) so docstring type references link out. - Add .readthedocs.yaml and docs/requirements.txt for an explicit, modern RTD build config. - Add a Dectris Arina usage example to docs/index.rst. - Fix RST syntax bugs in docstrings (eels.pre_post_fit, gaussND.gauss3D_FIT, multicorr_funcs.imageShifter, smv.smvWriter, line_profile.line_profile) and set napoleon_use_ivar to stop __slots__-based classes like fileDM from being documented twice. Verified with `sphinx-build -W`: warnings dropped from 30 to 7, all remaining ones pre-existing (missing edstomo extra, deprecated theme call, empty tools toctree entry). Co-Authored-By: Claude --- .gitignore | 4 +- .readthedocs.yaml | 18 +++++++ docs/conf.py | 31 ++++++++++++ docs/index.rst | 14 +++++ docs/ncempy.algo.rst | 93 ---------------------------------- docs/ncempy.command_line.rst | 22 -------- docs/ncempy.edstomo.rst | 54 -------------------- docs/ncempy.eval.rst | 29 ----------- docs/ncempy.io.rst | 53 ------------------- docs/ncempy.rst | 15 ------ docs/ncempy.viz.rst | 7 --- docs/requirements.txt | 3 ++ ncempy/algo/eels.py | 2 + ncempy/algo/gaussND.py | 3 -- ncempy/algo/multicorr_funcs.py | 7 +-- ncempy/eval/line_profile.py | 2 +- ncempy/io/smv.py | 2 +- 17 files changed, 74 insertions(+), 285 deletions(-) create mode 100644 .readthedocs.yaml delete mode 100644 docs/ncempy.algo.rst delete mode 100644 docs/ncempy.command_line.rst delete mode 100644 docs/ncempy.edstomo.rst delete mode 100644 docs/ncempy.eval.rst delete mode 100644 docs/ncempy.io.rst delete mode 100644 docs/ncempy.rst delete mode 100644 docs/ncempy.viz.rst create mode 100644 docs/requirements.txt diff --git a/.gitignore b/.gitignore index c3ec761..304ddfa 100644 --- a/.gitignore +++ b/.gitignore @@ -90,7 +90,9 @@ ncempy/venv # Rope project settings .ropeproject -sphinx-apidoc + +# Auto-generated by sphinxcontrib.apidoc on each docs build (see docs/conf.py) +docs/ncempy*.rst # Vim tags diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..00555b1 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,18 @@ +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + fail_on_warning: false + +python: + install: + - method: pip + path: . + extra_requirements: + - jupyter + - requirements: docs/requirements.txt diff --git a/docs/conf.py b/docs/conf.py index 9977095..2e2bd0b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,10 +34,41 @@ 'sphinx.ext.todo', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', + 'sphinx.ext.intersphinx', + 'sphinxcontrib.apidoc', ] napoleon_include_init_with_doc = False +# Document docstring "Attributes" sections as :ivar: fields instead of as +# separate autodoc attribute entries. Several classes (e.g. ncempy.io.dm.fileDM) +# declare their attributes via __slots__, which autodoc also picks up directly; +# without this, each one is documented twice and Sphinx raises "duplicate +# object description" warnings. +napoleon_use_ivar = True + +# -- sphinxcontrib.apidoc --------------------------------------------------- +# Regenerates the ncempy.*.rst stub files from the package source on every +# build, instead of hand-maintaining them. This keeps the module list from +# drifting out of sync with the actual submodules. +apidoc_module_dir = '../ncempy' +apidoc_output_dir = '.' +apidoc_excluded_paths = ['test'] +apidoc_separate_modules = True +apidoc_module_first = True +apidoc_toc_file = False + +# -- sphinx.ext.intersphinx -------------------------------------------------- +# Lets type references in docstrings (e.g. `numpy.ndarray`) link out to the +# referenced project's own docs. +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'numpy': ('https://numpy.org/doc/stable/', None), + 'scipy': ('https://docs.scipy.org/doc/scipy/', None), + 'h5py': ('https://docs.h5py.org/en/stable/', None), + 'matplotlib': ('https://matplotlib.org/stable/', None), +} + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 92bb803..51457a6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,6 +61,20 @@ Here is how to open a DM file and have access to the internal file parameters >>> print(dm0.metaData) # all of the interesting metadata for this data set (pixel size, accelerating voltage, etc.) >>> print(dm0.allTags) # all of the tags in the file including tags specific to the Digital Micrpograph software program +Reading Dectris Arina 4D-STEM data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The Dectris Arina detector writes its 4D-STEM data set across an HDF5 master +file and one or more linked data files. Use `ncempy.io.dectris` to load the +full 4D data set from the master file. + +.. code-block:: python + + >>> import ncempy.io as nio + >>> with nio.dectris.fileDECTRIS('/path/to/file/master.h5') as f0: + >>> data = f0.getDataset() # the full 4D data set, shape [scanY, scanX, frameY, frameX] + >>> print(data['data'].shape) + >>> print(f0.getMetadata()) # scan metadata (e.g. pixel size), if available + License ------- diff --git a/docs/ncempy.algo.rst b/docs/ncempy.algo.rst deleted file mode 100644 index c82eb15..0000000 --- a/docs/ncempy.algo.rst +++ /dev/null @@ -1,93 +0,0 @@ -ncempy.algo package -=================== - -Submodules ----------- - -ncempy.algo.align module ------------------------- - -.. automodule:: ncempy.algo.align - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.distortion module ------------------------------ - -.. automodule:: ncempy.algo.distortion - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.fourier\_operations module --------------------------------------- - -.. automodule:: ncempy.algo.fourier_operations - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.local\_max module ------------------------------ - -.. automodule:: ncempy.algo.local_max - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.math module ------------------------ - -.. automodule:: ncempy.algo.math - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.moments module --------------------------- - -.. automodule:: ncempy.algo.moments - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.multicorr_funcs module ----------------------------- - -.. automodule:: ncempy.algo.multicorr_funcs - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.radial\_profile module ----------------------------------- - -.. automodule:: ncempy.algo.radial_profile - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.rebin module ------------------------- - -.. automodule:: ncempy.algo.rebin - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.gaussND module --------------------------- - -.. automodule:: ncempy.algo.gaussND - :members: - :undoc-members: - :show-inheritance: - -ncempy.algo.peak_find module ----------------------------- - -.. automodule:: ncempy.algo.peak_find - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/ncempy.command_line.rst b/docs/ncempy.command_line.rst deleted file mode 100644 index 98f5e51..0000000 --- a/docs/ncempy.command_line.rst +++ /dev/null @@ -1,22 +0,0 @@ -ncempy.command\_line package -============================ - -Submodules ----------- - -ncempy.command\_line.ncem2png module ------------------------------------- - -.. automodule:: ncempy.command_line.ncem2png - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: ncempy.command_line - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/ncempy.edstomo.rst b/docs/ncempy.edstomo.rst deleted file mode 100644 index dcd4172..0000000 --- a/docs/ncempy.edstomo.rst +++ /dev/null @@ -1,54 +0,0 @@ -ncempy.edstomo package -====================== - -Submodules ----------- - -ncempy.edstomo.CharacteristicEmission module --------------------------------------------- - -.. automodule:: ncempy.edstomo.CharacteristicEmission - :members: - :undoc-members: - :show-inheritance: - -ncempy.edstomo.DoGenfire module -------------------------------- - -.. automodule:: ncempy.edstomo.DoGenfire - :members: - :undoc-members: - :show-inheritance: - -ncempy.edstomo.bruker module ----------------------------- - -.. automodule:: ncempy.edstomo.bruker - :members: - :undoc-members: - :show-inheritance: - -ncempy.edstomo.postprocess module ---------------------------------- - -.. automodule:: ncempy.edstomo.postprocess - :members: - :undoc-members: - :show-inheritance: - -ncempy.edstomo.preprocess module --------------------------------- - -.. automodule:: ncempy.edstomo.preprocess - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: ncempy.edstomo - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/ncempy.eval.rst b/docs/ncempy.eval.rst deleted file mode 100644 index 1527999..0000000 --- a/docs/ncempy.eval.rst +++ /dev/null @@ -1,29 +0,0 @@ -ncempy.eval package -=================== - -Submodules ----------- - -ncempy.eval.line\_profile module --------------------------------- - -.. automodule:: ncempy.eval.line_profile - :members: - :undoc-members: - :show-inheritance: - -ncempy.eval.ring\_diff module ------------------------------ - -.. automodule:: ncempy.eval.ring_diff - :members: - :undoc-members: - :show-inheritance: - -ncempy.eval.stack\_align module -------------------------------- - -.. automodule:: ncempy.eval.stack_align - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/ncempy.io.rst b/docs/ncempy.io.rst deleted file mode 100644 index 6a5b2fa..0000000 --- a/docs/ncempy.io.rst +++ /dev/null @@ -1,53 +0,0 @@ -ncempy.io package -================= - -Submodules ----------- - -ncempy.io.read module ---------------------- - -.. automodule:: ncempy.io.read - :members: - :undoc-members: - -ncempy.io.emd module --------------------- - -.. automodule:: ncempy.io.emd - :members: - :undoc-members: - -ncempy.io.dm module -------------------- - -.. automodule:: ncempy.io.dm - :members: - -ncempy.io.emdVelox module -------------------------- - -.. automodule:: ncempy.io.emdVelox - :members: - :undoc-members: - -ncempy.io.mrc module --------------------- - -.. automodule:: ncempy.io.mrc - :members: - :undoc-members: - -ncempy.io.ser module --------------------- - -.. automodule:: ncempy.io.ser - :members: - :undoc-members: - -ncempy.io.smv module --------------------- - -.. automodule:: ncempy.io.smv - :members: - :undoc-members: \ No newline at end of file diff --git a/docs/ncempy.rst b/docs/ncempy.rst deleted file mode 100644 index 98806ff..0000000 --- a/docs/ncempy.rst +++ /dev/null @@ -1,15 +0,0 @@ -ncempy package -============== - -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - ncempy.algo - ncempy.command_line - ncempy.edstomo - ncempy.eval - ncempy.io - ncempy.viz diff --git a/docs/ncempy.viz.rst b/docs/ncempy.viz.rst deleted file mode 100644 index 533570f..0000000 --- a/docs/ncempy.viz.rst +++ /dev/null @@ -1,7 +0,0 @@ -ncempy.viz package -================== - -.. automodule:: ncempy.viz - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..bf1b2d6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +sphinx-rtd-theme +sphinxcontrib-apidoc diff --git a/ncempy/algo/eels.py b/ncempy/algo/eels.py index 043d7b3..b5fe407 100644 --- a/ncempy/algo/eels.py +++ b/ncempy/algo/eels.py @@ -76,6 +76,8 @@ def pre_post_fit(energy_axis, spectra, pre, post, initial_parameters=(0, .15, .1 The function to fit to the pre- and post-edge signals. The default is a Gaussian-Lorentz mixture as defined in the function definition. The function must take the energy loss values as the first argument and the parameters to fit as subsequent arguments. + + Returns ------- : 2-tuple A tuple contains two 1D ndarrays. The first is the energy loss values for the signal and the second is the diff --git a/ncempy/algo/gaussND.py b/ncempy/algo/gaussND.py index 494c77c..06c41c4 100644 --- a/ncempy/algo/gaussND.py +++ b/ncempy/algo/gaussND.py @@ -324,9 +324,6 @@ def gauss3D_FIT(xyz, x0, y0, z0, sigma_x, sigma_y, sigma_z): Returns the value of a gaussian at a 2D set of points for the given standard deviations with maximum normalized to 1. The Gaussian axes are assumed to be 90 degrees from each other. - xyz - - x0, y0, z0 = the x, y, z centers of the Gaussian - sigma_x, sigma_y, sigma_z = The std. deviations of the Gaussian. Note ----- diff --git a/ncempy/algo/multicorr_funcs.py b/ncempy/algo/multicorr_funcs.py index af33404..f14f52d 100644 --- a/ncempy/algo/multicorr_funcs.py +++ b/ncempy/algo/multicorr_funcs.py @@ -1,10 +1,5 @@ """ Module to correlate two images, functionally written. - -TODO ----- - - Cant use rfft2 currently. This gives one shift as 1/2 the value. How - can this be improved to improve speed? """ import numpy as np @@ -208,7 +203,7 @@ def imageShifter(g1, xy_shift): Multiply im by a plane wave that has the real space effect of shifting ifft2(G2) by [x, y] pixels. Parameters - ----------- + ---------- g1 : complex ndarray The Fourier transform of an image. xy_shift : list diff --git a/ncempy/eval/line_profile.py b/ncempy/eval/line_profile.py index a01a28c..32adac7 100644 --- a/ncempy/eval/line_profile.py +++ b/ncempy/eval/line_profile.py @@ -65,7 +65,7 @@ def line_profile(im0, p0, p1, num_points, width=0, step=0.5): -------- >> line, (xx, yy) = line_profile(image, (0, 100), (175, 100), 50, step=0.5, width=5) >> fg, ax = plt.subplots(1, 2) - >> ax[0].plot(line, '*-') + >> ax[0].plot(line, '-') >> ax[1].imshow(image) >> ax[1].scatter(yy, xx) """ diff --git a/ncempy/io/smv.py b/ncempy/io/smv.py index b6434a4..9b05669 100644 --- a/ncempy/io/smv.py +++ b/ncempy/io/smv.py @@ -237,7 +237,7 @@ def smvWriter(out_path, dp, camera_length=110, lamda=0.0197, pixel_size=0.01, newline : str (optional) Allow the user to specify the newline character. For data written on Windows computers some processing programs in Linux are not able to load SMV files with Windows - carriage return and newline characters. Use '\n' on Windows machines to enforce Linux + carriage return and newline characters. Use '\\n' on Windows machines to enforce Linux line endings. The default `None` will use the system default. custom_header : dict This allows the user to input custom header lines using a dictionary. Each key/value From 572b46fb2593dd5170b650a7bd798ccf8a41815b Mon Sep 17 00:00:00 2001 From: xPeterS Date: Mon, 13 Jul 2026 15:23:05 -0700 Subject: [PATCH 2/2] Document python_titan in the Components section Add a short description of python_titan as a set of open source automation packages for Thermo Fisher transmission electron microscopes, in both README.rst and docs/index.rst. Co-Authored-By: Claude --- README.rst | 3 +++ docs/index.rst | 3 +++ 2 files changed, 6 insertions(+) diff --git a/README.rst b/README.rst index 23c86c6..bcb59c0 100644 --- a/README.rst +++ b/README.rst @@ -29,6 +29,9 @@ The openNCEM collection comes with different components, described below. **tools** The tools build leveraging the algorithms and routines provided in the libraries/packages. They are subordered by the different problems they address. +**python_titan** + A set of open source automation packages for Thermo Fisher transmission electron microscopes. + Commands ======== diff --git a/docs/index.rst b/docs/index.rst index 51457a6..e6ddf84 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,6 +29,9 @@ The openNCEM collection comes with different components. The general functionali ncempy - openNCEM's python package tools - wrapping the provided functionality into useful tools +**python_titan** + A set of open source automation packages for Thermo Fisher transmission electron microscopes. + Examples -------- Simple file reading