Merge pull request diffpy#83 from yucongalicechen/pkg_docs

added package docs and corrected import in tools

Author: sbillinge

doc/manual/source/examples/toolsexample.rst

@@ -5,7 +5,7 @@
 Tools Example
 #############
 
-This example will demonstrate how diffpy.utils allows us to load and manage username and email information.
+This example will demonstrate how diffpy.utils allows us to conveniently load and manage user and package information.
 Using the tools module, we can efficiently get them in terms of a dictionary.
 
 1) We have the function ``get_user_info`` that neatly returns a dictionary containing the username and email.
@@ -14,23 +14,22 @@ Using the tools module, we can efficiently get them in terms of a dictionary.
     from diffpy.utils.tools import get_user_info
     user_info = get_user_info()
 
-   This function will first attempt to load configuration files
-   from both the current working directory and the home directory.
-   If no configuration files exist, it prompts for user input and creates a configuration file in the home directory.
-   It prioritizes prompted user inputs, then current working directory, and finally home directory.
-   If no configuration files or inputs are found, this function creates a configuration in the home directory
-   with empty values for username and email stored as a dictionary.
+   This function will first attempt to load the information from configuration files looking first in
+   the current working directory and then in the user's home directory.
+   If no configuration files exist, it prompts for user input and creates a configuration file in the home directory
+   so that the next time the program is run it will no longer have to prompt the user.
+   It can be passed user information which overrides looking in config files, and so could be passed
+   information that is entered through a gui or command line interface to override default information at runtime.
+   It prioritizes prompted user inputs, then current working directory config file, and finally home directory config file.
 
-2) You can also override existing values by passing a dictionary to the function. ::
+   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"` ::
 
     new_args = {"username": "new_username", "email": "[email protected]"}
     new_user_info = get_user_info(new_args)
 
-   Here, the function returns a dictionary containing the new arguments.
-   If no configuration files exist, it prompts for inputs again. The arguments passed here also override input values.
-   The updated arguments will not be saved in files.
-
-   You can update only the username or email individually, for example ::
+3) You can update only the username or email individually, for example ::
 
     new_username = {"username": new_username}
     new_user_info = get_user_info(new_username)
@@ -43,5 +42,18 @@ Using the tools module, we can efficiently get them in terms of a dictionary.
 
    This updates the email to "[email protected]" 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
+   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. ::
+
+    from diffpy.utils.tools import get_user_info
+    package_metadata = get_package_info("my_package")
+
+   You can also specify an existing dictionary to be updated with the information. ::
+
+    existing_dict = {"key": "value"}
+    updated_dict = get_package_info("my_package", metadata=existing_dict))
 
-By using this function, we ensure that user information is correctly loaded, merged, and saved.
+    note that `"diffpy.utils"` is automatically included in the package info since the `get_user_info` function is
+    part of diffpy.utils. 

doc/manual/source/utilities/toolsutility.rst

@@ -5,10 +5,19 @@
 Tools Utility
 #############
 
-The ``diffpy.utils.tools`` module contains tool functions for use with diffpy apps.
-One of these functions, ``get_user_info``, is designed for managing and tracking username and email information.
-This function helps storing this data in a ``diffpyconfig.json`` file.
+The ``diffpy.utils.tools`` module provides tool functions for use with diffpy apps.
 
-Users can use the module to simplify the process of loading, merging, and saving information consistently and easily.
+1) ``get_uder_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.
+
+2) ``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. 

src/diffpy/utils/tools.py

@@ -1,4 +1,4 @@
-import importlib
+import importlib.metadata
 import json
 import os
 from copy import copy