Merge pull request #87 from Sparks29032/doc_refactor

sbillinge · web-flow · commit dc460ca87659 · 2024-06-13T17:33:10.000-04:00
Fix up Documentation
diff --git a/doc/Makefile b/doc/Makefile
diff --git a/doc/manual/source/release.rst b/doc/manual/source/release.rst
diff --git a/doc/manual/source/utilities/toolsutility.rst b/doc/manual/source/utilities/toolsutility.rst
diff --git a/doc/source/api/diffpy.utils.parsers.rst b/doc/source/api/diffpy.utils.parsers.rst
diff --git a/doc/source/api/diffpy.utils.rst b/doc/source/api/diffpy.utils.rst
@@ -1,4 +1,4 @@
-:tocdepth: 2
+:tocdepth: -1
 
 diffpy.utils package
 ====================
@@ -19,10 +19,10 @@ Subpackages
 Submodules
 ----------
 
-diffpy.utils.version module
----------------------------
+diffpy.utils.tools module
+-------------------------
 
-.. automodule:: diffpy.utils.version
+.. automodule:: diffpy.utils.tools
     :members:
     :undoc-members:
     :show-inheritance:
diff --git a/doc/source/api/diffpy.utils.wx.rst b/doc/source/api/diffpy.utils.wx.rst
@@ -1,3 +1,5 @@
+.. _wx Python Utilities Documentation
+
 diffpy.utils.wx package
 =======================
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -16,13 +16,14 @@
 import os
 import sys
 import time
+from importlib.metadata import version
 
 # 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
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath("../../.."))
-sys.path.insert(0, os.path.abspath("../../../src"))
+sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath("../../src"))
 
 # abbreviations
 ab_authors = "Pavol Juhás, Timur Davis, Christopher L. Farrow, Simon J.L. Billinge group"
@@ -63,7 +64,6 @@
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-from importlib.metadata import version
 
 fullversion = version(project)
 # The short X.Y version.
@@ -206,16 +206,16 @@
 
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
-    #'papersize': 'letterpaper',
+    # 'papersize': 'letterpaper',
     # The font size ('10pt', '11pt' or '12pt').
-    #'pointsize': '10pt',
+    # 'pointsize': '10pt',
     # Additional stuff for the LaTeX preamble.
-    #'preamble': '',
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
+# author, documentclass [howto, manual, or own class]).
 latex_documents = [
     ("index", "diffpy.utils.tex", "diffpy.utils Documentation", ab_authors, "manual"),
 ]
diff --git a/doc/source/examples/exampledata/parserdata.zip b/doc/source/examples/exampledata/parserdata.zip
diff --git a/doc/source/examples/examples.rst b/doc/source/examples/examples.rst
@@ -1,6 +1,6 @@
 .. _Examples:
 
-:tocdepth: 2
+:tocdepth: -1
 
 Examples
 ########
@@ -9,3 +9,4 @@ Landing page for diffpy.utils examples.
 .. toctree::
     parsersexample
     resampleexample
+    toolsexample
diff --git a/doc/source/examples/parsersexample.rst b/doc/source/examples/parsersexample.rst
@@ -1,6 +1,6 @@
 .. _Parsers Example:
 
-:tocdepth: 2
+:tocdepth: -1
 
 Parsers Example
 ###############
@@ -51,7 +51,7 @@ Using the parsers module, we can load file data into simple and easy-to-work-wit
      hdata = loadData('<PATH to data.txt>', comments=['$', '-->'], headers=True)
 
 4) Rather than working with separate ``data_table`` and ``hdata`` objects, it may be easier to combine them into a single
-dictionary. We can do so using the ``serialize_data`` function. ::
+   dictionary. We can do so using the ``serialize_data`` function. ::
 
      from diffpy.utils.parsers import serialize_data
      file_data = serialize_data('<PATH to data.txt', hdata, data_table)
@@ -82,7 +82,7 @@ dictionary. We can do so using the ``serialize_data`` function. ::
      parsed_file_data = serialize_data('<PATH to data.txt>', hdata, data_table, serial_file='<PATH to serialfile.json>')
 
    The returned value, ``parsed_file_data``, is the dictionary we just added to ``serialfile.json``.
-   To extract the data from the serial file, we use ``deserialize_data''. ::
+   To extract the data from the serial file, we use ``deserialize_data``. ::
 
      from diffpy.utils.parsers import deserialize_data
      parsed_file_data = deserialize_data('<PATH to serialdata.json>')
diff --git a/doc/source/examples/resampleexample.rst b/doc/source/examples/resampleexample.rst
@@ -1,6 +1,6 @@
 .. _Resample Example:
 
-:tocdepth: 2
+:tocdepth: -1
 
 Resampling Example
 ##################
diff --git a/doc/source/examples/toolsexample.rst b/doc/source/examples/toolsexample.rst
@@ -1,6 +1,6 @@
 .. _Tools Example:
 
-:tocdepth: 2
+:tocdepth: -1
 
 Tools Example
 #############
@@ -24,7 +24,7 @@ Using the tools module, we can efficiently get them in terms of a dictionary.
 
    The function returns a dictionary containing the username and email information.
 
-2) You can also override existing values by passing a dictionary to the function with the keys `"username"` and `"email"` ::
+2) You can also override existing values by passing a dictionary to the function with the keys ``"username"`` and ``"email"`` ::
 
     new_args = {"username": "new_username", "email": "new@example.com"}
     new_user_info = get_user_info(new_args)
@@ -37,12 +37,12 @@ Using the tools module, we can efficiently get them in terms of a dictionary.
    This updates username to "new_username" while fetching the email from inputs or the configuration files.
    Similarly, you can update only the email. ::
 
-    new_email = {"email": new@email.com}
-    new_user_info = get_user_info(new_email)
+     new_email = {"email": new@email.com}
+     new_user_info = get_user_info(new_email)
 
    This updates the email to "new@email.com" while fetching the username from inputs or the configuration files.
 
-3) We also have the function ``get_package_info``, which inserts or updates package names and versions
+4) We also have the function ``get_package_info``, which inserts or updates package names and versions
    in the given metadata dictionary under the key "package_info".
    It stores the package information as {"package_info": {"package_name": "version_number"}}.
    This function can be used as follows. ::
@@ -55,5 +55,5 @@ Using the tools module, we can efficiently get them in terms of a dictionary.
     existing_dict = {"key": "value"}
     updated_dict = get_package_info("my_package", metadata=existing_dict))
 
-    note that `"diffpy.utils"` is automatically included in the package info since the `get_user_info` function is
-    part of diffpy.utils. 
+   note that `"diffpy.utils"` is automatically included in the package info since the `get_user_info` function is
+   part of diffpy.utils. 
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -11,13 +11,16 @@ The diffpy.utils package provides general functions for extracting data from var
 some PDF-specific functionality. These include wx GUI utilities used by the PDFgui program and an interpolation function
 based on the Whittaker-Shannon formula for resampling a bandlimited PDF or other profile function.
 
+Click :ref:`here<Utilities>` for a full list of utilities offered by diffpy.utils.
+
 ========
 Examples
 ========
 Illustrations of when and how one would use various diffpy.utils functions.
 
 * :ref:`File Data Extraction<Parsers Example>`
-* :ref:`Resampling & Data Reconstruction<Resample Example>`
+* :ref:`Resampling and Data Reconstruction<Resample Example>`
+* :ref:`Load and Manage User and Package Information<Tools Example>`
 
 =======
 Authors
@@ -46,6 +49,7 @@ Table of contents
 
    license
    release
+   Utilities <utilities/utilities>
    Examples <examples/examples>
    Package API <api/diffpy.utils>
 
diff --git a/doc/source/license.rst b/doc/source/license.rst
@@ -1,4 +1,4 @@
-:tocdepth: 2
+:tocdepth: -1
 
 .. index:: license
 
diff --git a/doc/source/release.rst b/doc/source/release.rst
@@ -0,0 +1,5 @@
+:tocdepth: -1
+
+.. index:: release notes
+
+.. include:: ../../CHANGELOG.rst
diff --git a/doc/source/utilities/parsersutility.rst b/doc/source/utilities/parsersutility.rst
@@ -0,0 +1,23 @@
+.. _Parsers Utility:
+
+Parsers Utility
+===============
+
+The ``diffpy.utils.parsers`` module allows users to easily and robustly load file data into a Python project.
+
+- ``loadData()``: Find and load a data table/block from a text file. This seems to work for most datafiles
+  including those generated by diffpy programs. Running only ``numpy.loadtxt`` will result in errors
+  for most these files as there is often excess data or parameters stored above the data block.
+  Users can instead choose to load all the parameters of the form ``<param_name> = <param_value>`` into a dictionary
+  with this function by setting the ``header`` parameter to ``True``.
+
+  The program identifies data blocks as the first matrix block with a constant number of columns.
+  A user can tune the minimum number of rows this matrix block must have.
+
+- ``deserialize_data()``: Load data from a serial file format into a Python dictionary. Currently, the only supported
+  serial format is ``.json``.
+
+- ``serialize_data()``: Serialize the data generated by ``loadData()`` into a serial file format. Currently, the only
+  supported serial format is ``.json``.
+
+For a more in-depth tutorial for how to use these parser utilities, click :ref:`here <Parsers Example>`.
diff --git a/doc/source/utilities/resampleutility.rst b/doc/source/utilities/resampleutility.rst
@@ -0,0 +1,9 @@
+.. _Resample Utility:
+
+Resample Utility
+================
+
+- ``wsinterp()``: Allows users easily reample a PDF onto another grid.
+  This makes use of the Whittaker-Shannon interpolation formula.
+  To see the theory behind how this interpolation works and how to use
+  it in practice, click :ref:`here <Resample Example>`.
diff --git a/doc/source/utilities/toolsutility.rst b/doc/source/utilities/toolsutility.rst
@@ -0,0 +1,23 @@
+.. _Tools Utility:
+
+Tools Utility
+=============
+
+The ``diffpy.utils.tools`` module provides tool functions for use with diffpy apps.
+
+- ``get_user_info()``: This function is designed for managing and tracking username and email information.
+
+  Developers can use this function to simplify the process of loading, merging, and saving information consistently and easily.
+  Additionally, it saves the effort of re-entering information, and allows overriding current information by
+  passing parameters.
+
+- ``get_package_info()``: This function loads package name and version information into a dictionary.
+  It updates the package information under the key "package_info" in the format {"package_name": "version_number"},
+  resulting in an entry in the passed metadata dictionary that looks like
+  ``{"package_info": {"package1": "version_number1", "package2": "version_number2"}`` if the function is called more than
+  once.
+
+  Users can use these functions to track and manage versions of packages that can later be stored, for example, in an output 
+  file header. 
+
+For a more in-depth tutorial for how to use these tools, click :ref:`here <Tools Example>`.
diff --git a/doc/source/utilities/utilities.rst b/doc/source/utilities/utilities.rst
@@ -0,0 +1,15 @@
+.. _Utilities:
+
+:tocdepth: -1
+
+Utilities
+#########
+Overview of utilities offered by ``diffpy.utils``.
+Check the :ref:`examples<Examples>` provided for how to use these.
+
+.. contents::
+   :depth: 2
+
+.. include:: parsersutility.rst
+.. include:: resampleutility.rst
+.. include:: toolsutility.rst
diff --git a/src/diffpy/utils/parsers/loaddata.py b/src/diffpy/utils/parsers/loaddata.py
@@ -28,13 +28,12 @@ def loadData(filename, minrows=10, headers=False, hdel="=", hignore=None, **kwar
         Name of the file we want to load data from.
     minrows: int
         Minimum number of rows in the first data block. All rows must have the same number of floating
-         point values.
+        point values.
     headers: bool
-     when False (defualt), the function returns a numpy array of the data in the data block.
+        when False (defualt), the function returns a numpy array of the data in the data block.
         When True, the function instead returns a dictionary of parameters and their corresponding
-         values parsed from
-        header (information prior the data block). See hdel and hignore for options to help with parsing header
-        information.
+        values parsed from header (information prior the data block). See hdel and hignore for options
+        to help with parsing header information.
     hdel: str
         (Only used when headers enabled.) Delimiter for parsing header information (default '='). e.g. using
         default hdel, the line 'parameter = p_value' is put into the dictionary as {parameter: p_value}.
diff --git a/src/diffpy/utils/parsers/resample.py b/src/diffpy/utils/parsers/resample.py
@@ -24,8 +24,7 @@ def wsinterp(x, xp, fp, left=None, right=None):
     """One-dimensional Whittaker-Shannon interpolation.
 
     This uses the Whittaker-Shannon interpolation formula to interpolate the value of fp (array),
-     which is defined over
-    xp (array), at x (array or float).
+    which is defined over xp (array), at x (array or float).
 
     Parameters
     ----------
@@ -37,8 +36,7 @@ def wsinterp(x, xp, fp, left=None, right=None):
         Function to be interpolated.
     left: float
         If given, set fp for x < xp[0] to left. Otherwise, if left is None (default) or not given,
-         set fp for x < xp[0]
-        to fp evaluated at xp[-1].
+        set fp for x < xp[0] to fp evaluated at xp[-1].
     right: float
         If given, set fp for x > xp[-1] to right. Otherwise, if right is None (default) or not given, set fp for
         x > xp[-1] to fp evaluated at xp[-1].
diff --git a/src/diffpy/utils/tools.py b/src/diffpy/utils/tools.py

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _wx Python Utilities Documentation`
	`2`	`+`
`1`	`3`	`diffpy.utils.wx package`
`2`	`4`	`=======================`
`3`	`5`