fix docstrings for error-free sphinx

ixdat · Nov 27, 2024 · 8111b9e · 8111b9e
1 parent fdfc363
commit 8111b9e
Show file tree

Hide file tree

Showing 22 changed files with 220 additions and 164 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -44,6 +44,7 @@
     "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
     "nbsphinx",
 ]
 
@@ -70,4 +71,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
diff --git a/docs/source/extended-concept.rst → ...source/diving_deeper/extended-concept.rst b/docs/source/extended-concept.rst → ...source/diving_deeper/extended-concept.rst
@@ -4,7 +4,7 @@
 Extended concept
 ================
 
-.. figure:: figures/ixdat_profile_pic.svg
+.. figure:: ../figures/ixdat_profile_pic.svg
     :width: 200
 
     The power of combining techniques (fig made with ``EC_Xray``, an ``ixdat`` precursor)

diff --git a/docs/source/diving_deeper/index.rst b/docs/source/diving_deeper/index.rst
@@ -19,3 +19,4 @@ The following sections contain the full documentation of readers, plotters and e
     backend
     plotter_docs/index
     exporter_docs/index
+    extended-concept.rst
diff --git a/docs/source/diving_deeper/structure_docs/measurement.rst b/docs/source/diving_deeper/structure_docs/measurement.rst
@@ -58,5 +58,5 @@ The ``measurements`` module
 Here is the full in-line documentation of the ``measurements`` module containing the
 ``Measurement`` class.
 
-.. automodule:: ixdat.measurements
+.. automodule:: ixdat.measurement_base
     :members:
diff --git a/docs/source/diving_deeper/structure_docs/technique_docs/ec_ms.rst b/docs/source/diving_deeper/structure_docs/technique_docs/ec_ms.rst
@@ -22,7 +22,7 @@ based on an electrochemical cyclic voltammatry program that are implemented in `
 (see :ref:`cyclic_voltammetry`).
 
 Finally, :ref:`deconvolution <deconvolution>` of mass spectrometry data from the diffusion broadening in the EC cell, described in `this publication <https://doi.org/10.1021/acs.analchem.1c00110>`_,
-is implemented in the deconvolution module, in a class inheriting from ``ECMSMeasurement``.
+is implemented in the ecms_calcualtors module, using the calculator class ``ECMSImpulseResponse``.
 
 ``ixdat`` has all the functionality and more for EC-MS data and analysis as the
 legacy `EC_MS <https://github.com/ScottSoren/EC_MS>`_ package. This includes the tools
@@ -66,9 +66,9 @@ Source: https://github.com/ixdat/ixdat/tree/user_ready/src/ixdat/techniques/ec_m
 
 .. _deconvolution:
 
-The ``deconvolution`` module
-----------------------------
-Source: https://github.com/ixdat/ixdat/tree/user_ready/src/ixdat/techniques/deconvolution.py
+The ``ecms_calculators`` module
+-------------------------------
+Source: https://github.com/ixdat/ixdat/tree/user_ready/src/ixdat/techniques/calculators/ecms_calculators.py
 
-.. automodule:: ixdat.techniques.deconvolution
+.. automodule:: ixdat.calculators.ecms_calculators
     :members:
diff --git a/docs/source/diving_deeper/structure_docs/technique_docs/electrochemistry.rst b/docs/source/diving_deeper/structure_docs/technique_docs/electrochemistry.rst
@@ -27,7 +27,7 @@ Electrochemistry is the most thoroughly developed technique in ``ixdat``. For in
 examples of the functionality in the ``ECMeasurement`` class and its subclasses, see
 the following Tutorials:
 
-- :ref:`data_in_and_out`
+- :ref:`data_tutorial`
 
 - :ref:`ec_tutorials`
 
@@ -74,7 +74,7 @@ For example, to coplot two cycles (the sedond and the 50th) which both start and
 Note that ``as_cv()`` is available for any hyphenated technique which inherits from ``ECMeasurement``,
 such as ``ECMSMeasurement``, and that all the data from the second technique (here MS)
 comes along for the ride when using the cycle counter to select data. For full documentation of the cyclic voltammetry
-module see below: :ref:`cv_module`
+module see below: :ref:`cyclic_voltammetry`
 
 .. _ec_module:
 
@@ -99,9 +99,9 @@ Source: https://github.com/ixdat/ixdat/tree/user_ready/src/ixdat/techniques/cv.p
 
 .. figure:: ../../../figures/cv_diff.svg
   :width: 300
-  :alt: Example ``CyclicVoltammagramDiff`` plot
+  :alt: Example ``CyclicVoltammogramDiff`` plot
 
-  output of ``CyclicVoltammagramDiff.plot()``.  `Tutorial <https://github.com/ixdat/tutorials/blob/main/loading_appending_and_saving/export_demo_data_as_csv.ipynb>`_.
+  output of ``CyclicVoltammogramDiff.plot()``.  `Tutorial <https://github.com/ixdat/tutorials/blob/main/loading_appending_and_saving/export_demo_data_as_csv.ipynb>`_.
 
 .. automodule:: ixdat.techniques.cv
     :members:
diff --git a/docs/source/diving_deeper/structure_docs/technique_docs/sec.rst b/docs/source/diving_deeper/structure_docs/technique_docs/sec.rst
@@ -33,7 +33,7 @@ and ``plot_wavelengths``). :ref:`Exporting SEC data <sec-exporter>` results in a
 the EC data and any tracked wavelengths and two auxiliary files with (i) the
 spectrum series and (ii) the reference spectrum.
 
-A :ref:`jupyter notebook tutorial <sec-tutorial>` for S-EC is available.
+A :ref:`jupyter notebook tutorial <sec_tutorial>` for S-EC is available.
 
 Fitting of spectroelectrochemistry data is not yet supported in ``ixdat``.
 

diff --git a/docs/source/questions.rst b/docs/source/questions.rst
@@ -28,7 +28,7 @@ Check out tutorials & cheat sheet:
 How do I get my data in an array form?
 ......................................
 
-:ref:`advanced_tutorials`
+:ref:`data_tutorial`
 :ref:`cheat_sheet`
 
 

diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst
@@ -43,6 +43,7 @@ As an open source project, ``ixdat`` is always happy to get contributions from t
 
 .. _readers_tutorial:
 
+
 Readers
 -------
 
@@ -122,9 +123,20 @@ Jupyter notebook file: https://github.com/ixdat/tutorials/blob/af1b38f2096555904
   an introduction to calibration.
 
 
+Demos
+-----
+Demos give a quick demonstration of many features of ixdat
+
+Jupiter notebook file: https://github.com/ixdat/tutorials/blob/main/demos/22E17_DTU/22E17_DTU_demo.ipynb
+
+.. toctree::
+  :maxdepth: 0
+
+  tutorials_repo/demos/22E17_DTU/22E17_DTU_demo
+
 
-The jupyter notebooks
----------------------
+The tutorials repo
+------------------
 
 All tutorials linked to above are also hosted and version controlled in the ixdat Tutorials repository:
 https://github.com/ixdat/tutorials/

diff --git a/src/ixdat/calculators/ecms_calculators.py b/src/ixdat/calculators/ecms_calculators.py
@@ -394,17 +394,18 @@ def from_measurement(
             measurement (ECMSMeasurement): Measurement including impulse response
                 measurment. Measurement needs to contain calibration data for mol
                 (either using ixdat native ECMSMeasurement.calibrate() or external
-                 package (eg siq's "quantifier"))
+                package (eg siq's "quantifier"))
             tspan (list): tspan over which to calculate the impulse response. Needs to
                 include zero.
             tspan_bg (list): tspan of background to subtract. If list of tspans
                 (list of lists) is passed, will interpolate between the points using
                 calc_linear_background()
             norm (bool): If true the impulse response is normalized to its
                 area. Default is True.
+            kwargs: Additional keyword arguments are passed on to
+                ECMSImpulseResponse.__init__
 
-            Additional keyword arguments are passed on to ECMSImpulseResponse.__init__
-        Return ECMSImpulseResponse
+        Return: ECMSImpulseResponse
         """
         print("Generating `ECMSImpulseResponse` from measurement.")
         if type(tspan_bg[0]) is not list:
@@ -674,7 +675,8 @@ def deconvolute_for_tspans(
         """
         Loops though list of tspans and associated t_zero list to deconvolute using
         the given impulse response (from model, but could also be from data) for
-        the molecule the impulse resp
+        the molecule.
+
         Args:
             tspan_list (list): list of tspans to devonvolute data over. if no t_zero
                 is given needs to include zero.
@@ -694,7 +696,7 @@ def deconvolute_for_tspans(
             export_data (bool): save raw and deconvoluted data as csv using name
 
         Return t_v_list (list): list of tuple of (time [s], deconvoluted MS signal
-                                [mol/s]) as returned from grab_deconvoluted_signal()
+            [mol/s]) as returned from grab_deconvoluted_signal()
         """
         measurement = measurement or self.measurement
         t_v_list = []

diff --git a/src/ixdat/exporters/csv_exporter.py b/src/ixdat/exporters/csv_exporter.py
@@ -40,15 +40,17 @@ def export(
         """Export a given measurement to a specified file.
 
         To improve flexibility with inheritance, this method delegates its work to:
-        - CSVExporter.prepare_header_and_data()
-        - CSVExporter.write_header()
-        - CSVExporter.write_data()
+
+        * CSVExporter.prepare_header_and_data()
+        * CSVExporter.write_header()
+        * CSVExporter.write_data()
 
         Args:
             measurement (Measurement): The measurement to export.
                 Defaults to self.measurement.
-                TODO: remove this kwarg. See conversation here:
-                   https://github.com/ixdat/ixdat/pull/30/files#r810926968
+                TODO:
+                    remove this kwarg. See conversation here:
+                    https://github.com/ixdat/ixdat/pull/30/files#r810926968
             path_to_file (Path): The path to the file to write. If it has no suffix,
                 a .csv suffix is appended. Defaults to f"{measurement.name}.csv"
             columns (list of str): The names of the data series to include. Defaults in

diff --git a/src/ixdat/exporters/ecms_exporter.py b/src/ixdat/exporters/ecms_exporter.py
@@ -39,8 +39,10 @@ def export(
                 a .csv suffix is appended. Defaults to f"{measurement.name}.csv"
             measurement (Measurement): The measurement to export.
                 Defaults to self.measurement.
-                TODO: remove this kwarg. See conversation here:
-                   https://github.com/ixdat/ixdat/pull/30/files#r810926968
+
+                TODO:
+                    remove this kwarg. See conversation here:
+                    https://github.com/ixdat/ixdat/pull/30/files#r810926968
             columns (list of str): The names of the data series to include. Defaults to
                 potential, current, and all MID signals.
             v_list: DEPRECATED. Use `columns` instead.

diff --git a/src/ixdat/exporters/spectrum_exporter.py b/src/ixdat/exporters/spectrum_exporter.py
@@ -23,8 +23,9 @@ def export(self, path_to_file, spectrum=None):
             path_to_file (str or Path): The path of the file to export to. Note that if a
                 file already exists with this path, it will be overwritten.
             spectrum (Spectrum): The spectrum to export if different from self.spectrum
-                TODO: remove this kwarg. See conversation here:
-                   https://github.com/ixdat/ixdat/pull/30/files#r810926968
+                TODO:
+                    remove this kwarg. See conversation here:
+                    https://github.com/ixdat/ixdat/pull/30/files#r810926968
         """
         from .. import Spectrum
 
@@ -78,8 +79,9 @@ def export(self, path_to_file=None, spectrum_series=None, spectra_as_rows=True):
         Args:
             spectrum_series (Spectrum): The spectrum_series to export if different from
                 self.spectrum_series
-                TODO: remove this kwarg. See conversation here:
-                   https://github.com/ixdat/ixdat/pull/30/files#r810926968
+                TODO:
+                    remove this kwarg. See conversation here:
+                    https://github.com/ixdat/ixdat/pull/30/files#r810926968
             path_to_file (str or Path): The path of the file to export to. Note that if a
                 file already exists with this path, it will be overwritten.
             spectra_as_rows (bool): This specifies the orientation of the data exported.