merging main

Author: sbillinge

.pre-commit-config.yaml

@@ -58,3 +58,10 @@ repos:
       - id: prettier
         additional_dependencies:
           - "prettier@^3.2.4"
+  # docformatter - formats docstrings using PEP 257
+  - repo: https://github.com/s-weigand/docformatter
+    rev: 5757c5190d95e5449f102ace83df92e7d3b06c6c
+    hooks:
+      - id: docformatter
+        additional_dependencies: [tomli]
+        args: [--in-place, --config, ./pyproject.toml]

doc/source/examples/tools_example.rst

@@ -41,7 +41,7 @@ The function will return
 
 .. code-block:: python
 
-        {"owner_email": "[email protected]", "owner_name": "Jane Doe", "owner_orcid": "0000-0000-0000-0000"}
+    {"owner_name": "Jane Doe", "owner_email": "[email protected]", "owner_orcid": "0000-0000-0000-0000"}
 
 
 Where does ``get_user_info()`` get the user information from?
@@ -77,6 +77,7 @@ When building an application where you want to capture data-owner information, w
 ``check_and_build_global_config()`` first followed by ``get_user_info`` in your app workflow.  E.g.,
 
 .. code-block:: python
+
     from diffpy.utils.tools import check_and_build_global_config, get_user_info
     from datetime import datetime
     import json
@@ -95,6 +96,24 @@ it will only run once.  However, if you want to bypass this behavior,
 ``check_and_build_global_config()`` takes an optional boolean ``skip_config_creation`` parameter that
 could be set to ``True`` at runtime to override the config creation.
 
+What happens when you run ``check_and_build_global_config()``?
+--------------------------------------------------------------
+
+When you set ``skip_config_creation`` to ``False`` and there is no existing global configuration file,
+the function will prompt you for inputs (name, email, ORCID).
+An example of the prompts you may see is:
+
+.. code-block:: python
+
+    Please enter the name you would want future work to be credited to: Jane Doe
+    Please enter your email: janedoe@example.com
+    Please enter your orcid ID if you know it: 0000-0000-0000-0000
+
+
+After receiving the inputs, the function will write the information to
+the `diffpyconfig.json` file in your home directory.
+
+
 ``check_and_build_global_config()`` returns ``True`` if the config file exists (whether it created it or not)
 and ``False`` if the config file does not exist in the user's home allowing you to develop your own
 workflow for handling missing config files after running it with ``skip_config_creation=True``.
@@ -104,7 +123,7 @@ I entered the wrong information in my config file so it always loads incorrect i
 
 It is easy to fix this simply by deleting the global and/or local config files, which will allow
 you to re-enter the information during the ``check_and_build_global_config()`` initialization
-workflow.   You can also simply editi the ``diffpyconfig.json`` file directly using a text
+workflow.   You can also simply edit the ``diffpyconfig.json`` file directly using a text
 editor.
 
 Locate the file ``diffpyconfig.json``, in your home directory and open it in an editor ::
@@ -115,7 +134,7 @@ Locate the file ``diffpyconfig.json``, in your home directory and open it in an
         "owner_orcid": "0000-0000-4321-1234"
     }
 
-   Then you can edit the username and email as needed, make sure to save your edits.
+Then you can edit the username and email as needed, make sure to save your edits.
 
 Automatically Capture Info about a Software Package Being Used
 ==============================================================

doc/source/utilities/tools_utility.rst

@@ -5,12 +5,17 @@ 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.
-
+- ``get_user_info()``: This function is designed for managing and tracking user information (name, email, orcid).
   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.
 
+- ``check_and_build_global_config()``: This function helps create a global configuration file
+  that can be used by, for example, ``get_user_info()``.
+  If no existing configuration file is found, this function prompts for information.
+  The provided inputs are then saved to a global configuration file.
+  This file can be reused later by ``get_user_info()`` to ensure that the work credits and user information are consistently stored.
+
 - ``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

news/class-docstring.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* class docstring for `DiffractionObject`
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/docformatter.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* docforamtter in pre-commit for automatic formatting of docstrings to PEP 257
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/pytest-comment.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Group's Pytest practices for using @pytest.mark.parametrize in test_diffraction_objects.py
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/pytest-reformat-transform.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: previous PR already contains has an news item for refactoring test_transform.py
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/test-func-format-compact.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* test comment format with compact style without extra line for each comment
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/user_info_doc.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* no news added: simply adding documentation for config update workflow
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/__init__.py

@@ -16,7 +16,6 @@
 # See LICENSE.rst for license information.
 #
 ##############################################################################
-
 """diffpy - tools for structure analysis by diffraction.
 
 Blank namespace package.