Update doc theme and fix doc strings (#294)

Update documentation theme to match SmartSim
and fix Python API doc strings.

[ committed by @mellis13 ]
[ reviewed by @billschereriii ]

doc/changelog.rst

@@ -12,6 +12,7 @@ This section details changes made in the development branch that have not yet be
 
 Description
 
+- Change documentation theme to sphinx_book_theme and fix doc strings
 - Add support for inspection of tensors and metadata inside datasets
 - Add support for user-directed logging for Python clients, using Client, Dataset, or LogContext logging methods
 - Add support for user-directed logging for C and Fortran clients without a Client or Dataset context
@@ -26,6 +27,7 @@ Description
 
 Detailed Notes
 
+- Change documentation theme to sphinx_book_theme to match SmartSim documentation theme and fix Python API doc string errors (PR294_)
 - Added support for retrieval of names and types of tensors and metadata inside datasets (PR291_)
 - Added support for user-directed logging for Python clients via {Client, Dataset, LogContext}.{log_data, log_warning, log_error} methods (PR289_)
 - Added support for user-directed logging without a Client or Dataset context to C and Fortran clients via _string() methods (PR288_)
@@ -42,8 +44,9 @@ Detailed Notes
 - Implemented support for Unix Domain Sockets, including refactorization of server address code, test cases, and check-in tests. (PR252_)
 - A new make target `make lib-with-fortran` now compiles the Fortran client and dataset into its own library which applications can link against (PR245_)
 
-.. _PR288: https://github.com/CrayLabs/SmartRedis/pull/291
-.. _PR288: https://github.com/CrayLabs/SmartRedis/pull/289
+.. _PR294: https://github.com/CrayLabs/SmartRedis/pull/294
+.. _PR291: https://github.com/CrayLabs/SmartRedis/pull/291
+.. _PR289: https://github.com/CrayLabs/SmartRedis/pull/289
 .. _PR288: https://github.com/CrayLabs/SmartRedis/pull/288
 .. _PR287: https://github.com/CrayLabs/SmartRedis/pull/287
 .. _PR286: https://github.com/CrayLabs/SmartRedis/pull/286

doc/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'SmartRedis'
-copyright = '2022, Hewlett Packard Enterprise'
+copyright = '2021-2023, Hewlett Packard Enterprise'
 author = 'Hewlett Packard Enterprise'
 
 # The full version, including alpha/beta/rc tags
@@ -68,7 +68,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
 
 # 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,

requirements-dev.txt

@@ -1,6 +1,6 @@
 numpy>=1.18.2
 sphinx==3.1.1
-sphinx_rtd_theme>=0.5.0
+sphinx-book-theme==0.2.0
 pytest>=6.0.0
 pytest-cov==2.10.1
 black==20.8b1
@@ -9,3 +9,4 @@ pylint==2.6.0
 breathe==4.26.0
 torch==1.7.1
 sphinx-fortran==1.1.1
+jinja2==3.0.3

src/python/module/smartredis/client.py

@@ -1438,9 +1438,9 @@ def copy_list(self, src_name, dest_name):
         See set_data_source() and use_list_ensemble_prefix()
         for more details.
 
-        :param  src_name The source list name
+        :param src_name: The source list name
         :type src_name: str
-        :param  dest_name The destination list name
+        :param dest_name: The destination list name
         :type dest_name: str
         :raises RedisReplyError: if there is an error
                 in command execution.
@@ -1458,9 +1458,9 @@ def rename_list(self, src_name, dest_name):
         the supplied old_name and new_name. See set_data_source()
         and use_list_ensemble_prefix() for more details.
 
-        :param  src_name The source list name
+        :param src_name: The source list name
         :type src_name: str
-        :param  dest_name The destination list name
+        :param dest_name: The destination list name
         :type dest_name: str
         :raises RedisReplyError: if there is an error
                 in command execution.
@@ -1473,7 +1473,7 @@ def rename_list(self, src_name, dest_name):
     def get_list_length(self, list_name):
         """Get the number of entries in the list
 
-        :param  list_name The list name
+        :param list_name: The list name
         :type list_name: str
         :return: The length of the list
         :rtype: int
@@ -1494,16 +1494,16 @@ def poll_list_length(self, name, list_length, poll_frequency_ms, num_tries):
         name. See set_data_source() and use_list_ensemble_prefix()
         for more details.
 
-        :param  name The name of the list
+        :param name: The name of the list
         :type name: str
-        :param  list_length The desired length of the list
+        :param list_length: The desired length of the list
         :type list_length: int
-        :param  poll_frequency_ms The time delay between checks, in milliseconds
+        :param poll_frequency_ms: The time delay between checks, in milliseconds
         :type poll_frequency_ms: int
-        :param  num_tries The total number of times to check for the name
+        :param num_tries: The total number of times to check for the name
         :type num_tries: int
-        :return:  Returns true if the list is found with a length greater
-                  than or equal to the provided length, otherwise false
+        :return: Returns true if the list is found with a length greater
+                than or equal to the provided length, otherwise false
         :rtype: bool
         :raises RedisReplyError: if there is an error
                 in command execution.
@@ -1526,16 +1526,16 @@ def poll_list_length_gte(self, name, list_length, poll_frequency_ms, num_tries):
         name. See set_data_source() and use_list_ensemble_prefix()
         for more details.
 
-        :param  name The name of the list
+        :param name: The name of the list
         :type name: str
-        :param  list_length The desired minimum length of the list
+        :param list_length: The desired minimum length of the list
         :type list_length: int
-        :param  poll_frequency_ms The time delay between checks, in milliseconds
+        :param poll_frequency_ms: The time delay between checks, in milliseconds
         :type poll_frequency_ms: int
-        :param  num_tries The total number of times to check for the name
+        :param num_tries: The total number of times to check for the name
         :type num_tries: int
-        :return:  Returns true if the list is found with a length greater
-                  than or equal to the provided length, otherwise false
+        :return: Returns true if the list is found with a length greater
+                 than or equal to the provided length, otherwise false
         :rtype: bool
         :raises RedisReplyError: if there is an error
                 in command execution.
@@ -1558,16 +1558,16 @@ def poll_list_length_lte(self, name, list_length, poll_frequency_ms, num_tries):
         name. See set_data_source() and use_list_ensemble_prefix()
         for more details.
 
-        :param  name The name of the list
+        :param name: The name of the list
         :type name: str
-        :param  list_length The desired maximum length of the list
+        :param list_length: The desired maximum length of the list
         :type list_length: int
-        :param  poll_frequency_ms The time delay between checks, in milliseconds
+        :param poll_frequency_ms: The time delay between checks, in milliseconds
         :type poll_frequency_ms: int
-        :param  num_tries The total number of times to check for the name
+        :param num_tries: The total number of times to check for the name
         :type num_tries: int
-        :return:  Returns true if the list is found with a length less
-                  than or equal to the provided length, otherwise false
+        :return: Returns true if the list is found with a length less
+                 than or equal to the provided length, otherwise false
         :rtype: bool
         :raises RedisReplyError: if there is an error
                 in command execution.
@@ -1589,9 +1589,9 @@ def get_datasets_from_list(self, list_name):
         for more details.  An empty or nonexistant
         aggregation list returns an empty vector.
 
-        :param  list_name The name of the list
+        :param list_name: The name of the list
         :type list_name: str
-        :return:  A list of DataSet objects.
+        :return: A list of DataSet objects.
         :rtype: list[DataSet]
         :raises RedisReplyError: if there is an error in command execution.
         """
@@ -1612,20 +1612,20 @@ def get_dataset_list_range(self, list_name, start_index, end_index):
         and end_index are inconsistent (e.g. end_index is less
         than start_index), an empty list of datasets will be returned.
 
-        :param  list_name The name of the list
+        :param list_name: The name of the list
         :type list_name: str
-        :param  start_index The starting index of the range (inclusive,
-                starting at zero).  Negative values are
-                supported.  A negative value indicates offsets
-                starting at the end of the list. For example, -1 is
-                the last element of the list.
+        :param start_index: The starting index of the range (inclusive,
+               starting at zero).  Negative values are
+               supported.  A negative value indicates offsets
+               starting at the end of the list. For example, -1 is
+               the last element of the list.
         :type start_index: int
-        :param end_index The ending index of the range (inclusive,
+        :param end_index: The ending index of the range (inclusive,
                starting at zero).  Negative values are
                supported.  A negative value indicates offsets
                starting at the end of the list. For example, -1 is
                the last element of the list.
-        :return:  A list of DataSet objects.
+        :return: A list of DataSet objects.
         :rtype: list[DataSet]
         :raises RedisReplyError: if there is an error in command execution.
         """