#211 Improve documentation

.github/linters/.jscpd.json

@@ -1 +1 @@
-{}
+{}

.github/workflows/pytest-linux.yaml

@@ -68,13 +68,15 @@ jobs:
         run: |
           source ./venv/bin/activate
           set +e
-          pytest examples/szconfig/ \
+          pytest \
+            examples/misc/ \
+            examples/extras/ \
+            examples/szabstractfactory/ \
+            examples/szconfig/ \
             examples/szconfigmanager/ \
             examples/szdiagnostic/ \
             examples/szengine/ \
             examples/szproduct/ \
-            examples/extras/ \
-            examples/misc/ \
             --capture=no \
             -o python_files=*.py \
             --verbose

docs/source/conf.py

@@ -7,7 +7,6 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import os
-import subprocess
 import sys
 
 project = "sz-sdk-python-grpc"
@@ -53,75 +52,3 @@
 html_theme = "sphinx_rtd_theme"
 # autodoc_inherit_docstrings = False  # don't include docstrings from the parent class
 # autodoc_typehints = "description"   # Show types only in descriptions, not in signatures
-
-# Setup for process_docstring()
-PROCESS_DOCSTRING_DEBUG = os.getenv("SPHINX_PROCESS_DOCSTRING_DEBUG", "")
-try:
-    # Running "locally" using Make
-    if not os.getenv("GITHUB_ACTIONS", ""):
-        print("\nPROCESS_DOCSTRING: Not running in a GitHub action...")
-
-        # Example response = 153-ant-1
-        git_branch = subprocess.run(
-            ["git", "symbolic-ref", "--short", "HEAD"], capture_output=True, check=True
-        ).stdout.decode(encoding="utf-8")
-
-        # Example response = git@github.com:senzing-garage/sz-sdk-python-core.git
-        git_repo = subprocess.run(
-            ["git", "config", "--get-all", "remote.origin.url"], capture_output=True, check=True
-        ).stdout.decode(encoding="utf-8")
-
-        # Capture only senzing-garage/sz-sdk-python-core
-        if git_repo:
-            git_repo_list = git_repo.split(":")
-            git_repo = git_repo_list[-1]
-            git_repo = git_repo.replace(".git", "")
-    else:
-        print("\nPROCESS_DOCSTRING: Running in a GitHub action...")
-        # Example response = 153-ant-1
-        git_branch = os.getenv("GITHUB_REF_NAME", "")
-        # Example response = senzing-garage/sz-sdk-python-core
-        git_repo = os.getenv("GITHUB_REPOSITORY", "")
-
-    git_branch = git_branch.strip()
-    git_repo = git_repo.strip()
-
-    print(f"PROCESS_DOCSTRING: {git_branch = }")
-    print(f"PROCESS_DOCSTRING: {git_repo = }\n")
-
-    if not git_branch or not git_repo:
-        raise ValueError("no value for either git_branch or git_repo")
-except (subprocess.CalledProcessError, FileNotFoundError, TypeError, IndexError, ValueError) as err:
-    print("ERROR: Failed processing doc strings: ")
-    raise err
-
-
-def process_abstract_docstring(app, what, name, obj, options, lines):
-    """
-    When processing doc strings from (abstract) sz-sdk-python check if any line in the doc string has a
-    remote import (rli directive) for the examples and output files in a concrete package (for example,
-    sz-sdk-python-core or sz-sdk-python-grpc).
-
-    If the rli directive is found and is referencing /examples/ replace /main/ with the current branch to
-    point to examples in that branch to build the docs and not the current main branch; examples in main
-    may not be current if the working branch has modified them.
-    """
-    if PROCESS_DOCSTRING_DEBUG:
-        print(f"\nPROCESS_DOCSTRING: {app = }")
-        print(f"PROCESS_DOCSTRING: {what = }")
-        print(f"PROCESS_DOCSTRING: {name = }")
-        print(f"PROCESS_DOCSTRING: {obj = }")
-        print(f"PROCESS_DOCSTRING: {options = }")
-        print(f"PROCESS_DOCSTRING: {lines = }")
-
-    for i, line in enumerate(lines):
-        # .. rli:: https://raw.githubusercontent.com/senzing-garage/sz-sdk-python-core/refs/heads/main/examples/szengine/add_record.py
-        if f".. rli:: https://raw.githubusercontent.com/{git_repo}/refs/heads/main/examples/" in line:
-            print(f"PROCESS_DOCSTRING: Replacing /main/ with /{git_branch}/ for {what} {name}, line: {line.strip()}")
-            lines[i] = line.replace("/main/", f"/{git_branch}/")
-            print(f"PROCESS_DOCSTRING:\t{lines[i].strip()}\n")
-
-
-def setup(app):
-    """Hook to autodoc to process docs strings from (abstract) sz-sdk-python"""
-    app.connect("autodoc-process-docstring", process_abstract_docstring)

docs/source/index.rst

@@ -3,20 +3,39 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-sz-sdk-python-grpc
-==================
+`senzing_grpc` Python package documentation
+===========================================
+
+The `senzing-grpc`_ Python package is a `gRPC`_ implementation of the
+`senzing`_ the interface definition.
+If an implementation is needed to communicate directly with the Senzing binaries,
+use the `senzing-core`_ Python package.
+
+Senzing has additional Software Development Kits (SDKs)
+for Java, Go, and C#.
+Information for these SDKs can be found at `docs.senzing.com`_.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   modules
-
+   senzing_grpc
 
+References
+==========
 
-Indices and tables
-==================
+#. :ref:`genindex`
+#. :ref:`modindex`
+#. :ref:`search`
+#. `GitHub`_
+#. `Pypi`_
+#. `senzing-core`_
+#. `senzing`_
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. _docs.senzing.com: https://www.senzing.com/docs
+.. _GitHub: https://github.com/senzing-garage/sz-sdk-python/tree/main/examples
+.. _gRPC: https://grpc.io
+.. _Pypi: https://pypi.org/project/senzing/
+.. _senzing-core: https://garage.senzing.com/sz-sdk-python-core
+.. _senzing-grpc: https://github.com/senzing-garage/sz-sdk-python-grpc
+.. _senzing: https://garage.senzing.com/sz-sdk-python

docs/source/senzing_grpc.rst

@@ -1,75 +1,89 @@
-senzing package
-===============
-
-Submodules
-----------
-
-senzing_grpc.szabstractfactory module
--------------------------------------
+senzing_grpc
+============
+
+The `senzing_grpc`_ Python package has 5 major modules / classes.
+Senzing objects are created using an `Abstract Factory Pattern`_.
+
+.. list-table:: Senzing classes
+   :widths: 20 20 60
+   :header-rows: 1
+
+   * - Module
+     - Class
+     - Creation
+   * - szconfig
+     - SzConfigGrpc
+     - `sz_config = sz_abstract_factory.create_config()`
+   * - szconfigmanager
+     - SzConfigManagerGrpc
+     - `sz_configmanager = sz_abstract_factory.create_configmanager()`
+   * - szdiagnostic
+     - SzDiagnosticGrpc
+     - `sz_diagnostic = sz_abstract_factory.create_diagnostic()`
+   * - szengine
+     - SzEngineGrpc
+     - `sz_engine = sz_abstract_factory.create_engine()`
+   * - szproduct
+     - SzProductGrpc
+     - `sz_product = sz_abstract_factory.create_product()`
+
+For the full implementation of the documentation examples, visit the source code on
+`GitHub`_.
+
+szabstractfactory
+-----------------
 
 .. automodule:: senzing_grpc.szabstractfactory
    :members:
    :undoc-members:
    :show-inheritance:
 
-senzing_grpc.szconfig module
-----------------------------
+szconfig
+--------
 
 .. automodule:: senzing_grpc.szconfig
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_grpc.szconfigmanager module
------------------------------------
+szconfigmanager
+---------------
 
 .. automodule:: senzing_grpc.szconfigmanager
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_grpc.szdiagnostic module
---------------------------------
+szdiagnostic
+------------
 
 .. automodule:: senzing_grpc.szdiagnostic
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_grpc.szengine module
-----------------------------
+szengine
+--------
 
 .. automodule:: senzing_grpc.szengine
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_grpc.szhelpers module
------------------------------
-
-.. automodule:: senzing_grpc.szhelpers
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-senzing_grpc.szproduct module
------------------------------
+szproduct
+---------
 
 .. automodule:: senzing_grpc.szproduct
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-Module contents
----------------
-
-.. automodule:: senzing_grpc
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :inherited-members:
+.. _Abstract Factory Pattern: https://en.wikipedia.org/wiki/Abstract_factory_pattern
+.. _GitHub: https://github.com/senzing-garage/sz-sdk-python-grpc/tree/main/examples
+.. _senzing-core: https://garage.senzing.com/sz-sdk-python-core
+.. _senzing_grpc: https://github.com/senzing-garage/sz-sdk-python-grpc

makefiles/linux.mk

@@ -36,6 +36,7 @@ coverage-osarch-specific:
 .PHONY: dependencies-for-development-osarch-specific
 dependencies-for-development-osarch-specific:
 
+
 .PHONY: dependencies-for-documentation-osarch-specific
 dependencies-for-documentation-osarch-specific:
 
@@ -74,13 +75,15 @@ test-osarch-specific:
 	$(info --- Unit tests -------------------------------------------------------)
 	@$(activate-venv); pytest tests/ --verbose --capture=no --cov=src --cov-report xml:coverage.xml
 	$(info --- Test examples using pytest -------------------------------------)
-	@$(activate-venv); pytest examples/szconfig/ \
+	@$(activate-venv); pytest \
+		examples/misc/ \
+		examples/extras/ \
+		examples/szabstractfactory/ \
+		examples/szconfig/ \
 		examples/szconfigmanager/ \
 		examples/szdiagnostic/ \
 		examples/szengine/ \
 		examples/szproduct/ \
-		examples/extras/ \
-		examples/misc/ \
 		--capture=no \
 		-o python_files=*.py \
 		--verbose; \

src/senzing_grpc/szabstractfactory.py

@@ -1,7 +1,11 @@
 #! /usr/bin/env python3
 
 """
-TODO: szabstractfactory.py
+``senzing_grpc.szabstractfactory.SzAbstractFactoryGrpc`` is a `gRPC`_ implementation
+of the `senzing.szabstractfactory.SzAbstractFactory`_ interface.
+
+.. _gRPC: https://grpc.io
+.. _senzing.szabstractfactory.SzAbstractFactory: https://garage.senzing.com/sz-sdk-python/senzing.html#module-senzing.szabstractfactory
 """
 
 # pylint: disable=E1101

src/senzing_grpc/szconfig.py

@@ -1,7 +1,11 @@
 #! /usr/bin/env python3
 
 """
-TODO: szconfig_grpc.py
+``senzing_grpc.szconfig.SzConfigGrpc`` is a `gRPC`_ implementation
+of the `senzing.szconfig.SzConfig`_ interface.
+
+.. _gRPC: https://grpc.io
+.. _senzing.szconfig.SzConfig: https://garage.senzing.com/sz-sdk-python/senzing.html#module-senzing.szconfig
 """
 
 # pylint: disable=E1101

src/senzing_grpc/szconfigmanager.py

@@ -1,7 +1,11 @@
 #! /usr/bin/env python3
 
 """
-TODO: szconfigmanager_grpc.py
+``senzing_grpc.szconfigmanager.SzConfigManagerGrpc`` is a `gRPC`_ implementation
+of the `senzing.szconfigmanager.SzConfigManager`_ interface.
+
+.. _gRPC: https://grpc.io
+.. _senzing.szconfigmanager.SzConfigManager: https://garage.senzing.com/sz-sdk-python/senzing.html#module-senzing.szconfigmanager
 """
 
 # pylint: disable=E1101

src/senzing_grpc/szdiagnostic.py

@@ -1,7 +1,11 @@
 #! /usr/bin/env python3
 
 """
-TODO: szdiagnostic_grpc.py
+``senzing_grpc.szdiagnostic.SzDiagnosticGrpc`` is a `gRPC`_ implementation
+of the `senzing.szdiagnostic.SzDiagnostic`_ interface.
+
+.. _gRPC: https://grpc.io
+.. _senzing.szdiagnostic.SzDiagnostic: https://garage.senzing.com/sz-sdk-python/senzing.html#module-senzing.szdiagnostic
 """
 
 # pylint: disable=E1101

src/senzing_grpc/szengine.py

@@ -1,7 +1,11 @@
 #! /usr/bin/env python3
 
 """
-TODO: szengine_grpc.py
+``senzing_grpc.szengine.SzEngineGrpc`` is a `gRPC`_ implementation
+of the `senzing.szengine.SzEngine`_ interface.
+
+.. _gRPC: https://grpc.io
+.. _senzing.szengine.SzEngine: https://garage.senzing.com/sz-sdk-python/senzing.html#module-senzing.szengine
 """
 
 # pylint: disable=E1101,C0302

src/senzing_grpc/szproduct.py

@@ -1,7 +1,11 @@
 #! /usr/bin/env python3
 
 """
-TODO: szproduct_grpc.py
+``senzing_grpc.szproduct.SzProductGrpc`` is a `gRPC`_ implementation
+of the `senzing.szproduct.SzProduct`_ interface.
+
+.. _gRPC: https://grpc.io
+.. _senzing.szproduct.SzProduct: https://garage.senzing.com/sz-sdk-python/senzing.html#module-senzing.szproduct
 """
 
 # pylint: disable=E1101