#192 Update documentation (#193)

* #192 Savepoint

* #192 Savepoint

* #192 Savepoint

* #192 Savepoint

* #192 Savepoint

* #192 Savepoint

.github/workflows/create-sphinx-documentation.yaml

@@ -2,10 +2,8 @@ name: Create sphinx documentation
 
 on:
   push:
-    branches: [main]
-    paths:
-      - "examples"
-      - "src"
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
   workflow_dispatch:
 
 permissions:
@@ -31,6 +29,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
+          python -m pip install --requirement requirements.txt
           python -m pip install --requirement documentation-requirements.txt
 
       - name: Sphinx build

.github/workflows/pytest-linux.yaml

@@ -75,13 +75,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/README.md

@@ -1,8 +1,8 @@
-# sz-sdk-python-grpc
+# sz-sdk-python-core
 
 Placeholder for [GitHub pages].
 
 See [GitHub page].
 
-[GitHub page]: https://garage.senzing.com/sz-sdk-python-grpc
+[GitHub page]: https://garage.senzing.com/sz-sdk-python-core
 [GitHub pages]: https://pages.github.com/

docs/errors.md

@@ -1 +1 @@
-# sz-sdk-python-grpc errors
+# sz-sdk-python-core errors

docs/examples.md

@@ -1,4 +1,4 @@
-# sz-sdk-python-grpc examples
+# sz-sdk-python-core examples
 
 ## Example TruthSet python
 

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-core"
@@ -52,75 +51,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 = [email protected]: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-core
-==================
+`senzing_core` Python package documentation
+===========================================
+
+The `senzing-core`_ Python package is an implementation of the
+`senzing`_ interface definition that communicates with the Senzing binaries.
+If an implementation is needed to communicate over `gRPC`_,
+use the `senzing-grpc`_ 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_core
 
+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://github.com/senzing-garage/sz-sdk-python-core
+.. _senzing-grpc: https://garage.senzing.com/sz-sdk-python-grpc
+.. _senzing: https://garage.senzing.com/sz-sdk-python

docs/source/senzing_core.rst

@@ -1,67 +1,89 @@
-senzing package
-===============
+senzing_core
+============
 
-Submodules
-----------
+The `senzing_core`_ Python package has 5 major modules / classes.
+Senzing objects are created using an `Abstract Factory Pattern`_.
 
-senzing_core.szabstractfactory module
--------------------------------------
+.. list-table:: Senzing classes
+   :widths: 20 20 60
+   :header-rows: 1
 
-.. automodule:: senzing_grpc.szabstractfactory
+   * - Module
+     - Class
+     - Creation
+   * - szconfig
+     - SzConfigCore
+     - `sz_config = sz_abstract_factory.create_config()`
+   * - szconfigmanager
+     - SzConfigManagerCore
+     - `sz_configmanager = sz_abstract_factory.create_configmanager()`
+   * - szdiagnostic
+     - SzDiagnosticCore
+     - `sz_diagnostic = sz_abstract_factory.create_diagnostic()`
+   * - szengine
+     - SzEngineCore
+     - `sz_engine = sz_abstract_factory.create_engine()`
+   * - szproduct
+     - SzProductCore
+     - `sz_product = sz_abstract_factory.create_product()`
+
+For the full implementation of the documentation examples, visit the source code on
+`GitHub`_.
+
+szabstractfactory
+-----------------
+
+.. automodule:: senzing_core.szabstractfactory
    :members:
    :undoc-members:
    :show-inheritance:
 
-senzing_core.szconfig module
-----------------------------
+szconfig
+--------
 
 .. automodule:: senzing_core.szconfig
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_core.szconfigmanager module
------------------------------------
+szconfigmanager
+---------------
 
 .. automodule:: senzing_core.szconfigmanager
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_core.szdiagnostic module
---------------------------------
+szdiagnostic
+------------
 
 .. automodule:: senzing_core.szdiagnostic
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_core.szengine module
-----------------------------
+szengine
+--------
 
 .. automodule:: senzing_core.szengine
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-senzing_core.szproduct module
------------------------------
+szproduct
+---------
 
 .. automodule:: senzing_core.szproduct
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:
 
-Module contents
----------------
-
-.. automodule:: senzing_core
-   :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-core/tree/main/examples
+.. _senzing_core: https://github.com/senzing-garage/sz-sdk-python-core
+.. _senzing-grpc: https://garage.senzing.com/sz-sdk-python-grpc

examples/szengine/add_record.py

@@ -1,27 +1,29 @@
 #! /usr/bin/env python3
 
+import json
+
 from senzing import SzEngineFlags, SzError
 
 from senzing_core import SzAbstractFactoryCore
 
 DATA_SOURCE_CODE = "TEST"
 FLAGS = SzEngineFlags.SZ_WITH_INFO
 INSTANCE_NAME = "Example"
-RECORD_DEFINITION = (
-    "{"
-    '"RECORD_TYPE": "PERSON",'
-    '"PRIMARY_NAME_LAST": "Smith",'
-    '"PRIMARY_NAME_FIRST": "Robert",'
-    '"DATE_OF_BIRTH": "12/11/1978",'
-    '"ADDR_TYPE": "MAILING",'
-    '"ADDR_LINE1": "123 Main Street, Las Vegas NV 89132",'
-    '"PHONE_TYPE": "HOME",'
-    '"PHONE_NUMBER": "702-919-1300",'
-    '"EMAIL_ADDRESS": "[email protected]",'
-    '"DATE": "1/2/18",'
-    '"STATUS": "Active",'
-    '"AMOUNT": "100"'
-    "}"
+RECORD_DEFINITION = json.dumps(
+    {
+        "RECORD_TYPE": "PERSON",
+        "PRIMARY_NAME_LAST": "Smith",
+        "PRIMARY_NAME_FIRST": "Robert",
+        "DATE_OF_BIRTH": "12/11/1978",
+        "ADDR_TYPE": "MAILING",
+        "ADDR_LINE1": "123 Main Street, Las Vegas NV 89132",
+        "PHONE_TYPE": "HOME",
+        "PHONE_NUMBER": "702-919-1300",
+        "EMAIL_ADDRESS": "[email protected]",
+        "DATE": "1/2/18",
+        "STATUS": "Active",
+        "AMOUNT": "100",
+    }
 )
 RECORD_ID = "1"
 SETTINGS = {