#181 Add documentation examples

.github/workflows/pytest-linux.yaml

@@ -78,6 +78,7 @@ jobs:
           set +e
           pytest \
             examples/misc/ \
+            examples/docs/ \
             examples/extras/ \
             examples/szabstractfactory/ \
             examples/szconfig/ \

docs/source/index.rst

@@ -3,8 +3,30 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to sz-sdk-python's documentation!
-=========================================
+`senzing` Python package documentation
+======================================
+
+The `senzing`_ Python package contains the interface definitions
+for the `senzing-core`_ and `senzing-grpc`_ implementation packages.
+
+By using interface definitions, implementation-agnostic code can be written.
+For example, the following code does not need to know the underlying implementation
+of the Senzing Abstract Factory:
+
+.. literalinclude:: ../../examples/docs/using_abstract_factory.py
+      :linenos:
+      :language: python
+
+Similarly, interface definitions for Senzing objects can be used.
+Example:
+
+.. literalinclude:: ../../examples/docs/using_sz_engine.py
+      :linenos:
+      :language: python
+
+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
@@ -20,3 +42,8 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. _docs.senzing.com: https://www.senzing.com/docs
+.. _senzing: https://github.com/senzing-garage/sz-sdk-python
+.. _senzing-core: https://garage.senzing.com/sz-sdk-python-core
+.. _senzing-grpc: https://garage.senzing.com/sz-sdk-python-grpc

docs/source/modules.rst

@@ -1,7 +1,35 @@
 senzing
 =======
 
+The `senzing` 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
+     - SzConfig
+     - `sz_config = sz_abstract_factory.create_config()`
+   * - szconfigmanager
+     - SzConfigManager
+     - `sz_configmanager = sz_abstract_factory.create_configmanager()`
+   * - szdiagnostic
+     - SzDiagnostic
+     - `sz_diagnostic = sz_abstract_factory.create_diagnostic()`
+   * - szengine
+     - SzEngine
+     - `sz_engine = sz_abstract_factory.create_engine()`
+   * - szproduct
+     - SzProduct
+     - `sz_product = sz_abstract_factory.create_product()`
+
 .. toctree::
    :maxdepth: 4
 
    senzing
+
+.. _Abstract Factory Pattern: https://en.wikipedia.org/wiki/Abstract_factory_pattern

docs/source/senzing.rst

@@ -1,6 +1,29 @@
 senzing package
 ===============
 
+In the examples, the creation of the Senzing objects has been abstracted to
+
+.. literalinclude:: ../../examples/docs/import_sz_abstract_factory.py
+      :linenos:
+      :language: python
+
+and
+
+.. literalinclude:: ../../examples/docs/import_sz_engine.py
+      :linenos:
+      :language: python
+
+Using the `senzing-core` Python package, the implementation looks like the following:
+
+
+.. literalinclude:: ../../examples/helpers/setup_senzing.py
+      :linenos:
+      :language: python
+
+Naturally, the `__init__.py` file needs to be modified to support importing the variables.
+For the full implementation of the documentation examples, visit the source code on
+`GitHub`_.
+
 Submodules
 ----------
 
@@ -67,3 +90,6 @@ Module contents
    :members:
    :undoc-members:
    :show-inheritance:
+
+
+.. _GitHub: https://github.com/senzing-garage/sz-sdk-python/tree/main/examples

examples/docs/__init__.py

@@ -0,0 +1,13 @@
+from ..helpers.setup_senzing import (
+    get_sz_abstract_factory,
+    get_sz_engine,
+    sz_abstract_factory,
+    sz_engine,
+)
+
+__all__ = [
+    "get_sz_abstract_factory",
+    "get_sz_engine",
+    "sz_abstract_factory",
+    "sz_engine",
+]

examples/docs/a_header_docs.py

@@ -0,0 +1,5 @@
+"""
+Simply a header used in development.
+"""
+
+print("\n---- docs ------------------------------------------------------------\n")

examples/docs/import_sz_abstract_factory.py

@@ -0,0 +1,3 @@
+from . import sz_abstract_factory
+
+sz_engine = sz_abstract_factory.create_engine()

examples/docs/import_sz_engine.py

@@ -0,0 +1,3 @@
+from . import sz_engine
+
+count = sz_engine.count_redo_records()

examples/docs/using_abstract_factory.py

@@ -0,0 +1,8 @@
+from senzing import SzAbstractFactory, SzEngineFlags
+
+
+def perform_senzing_search(sz_abstract_factory: SzAbstractFactory, attributes: str) -> str:
+    sz_engine = sz_abstract_factory.create_engine()
+    flags = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS
+    search_profile = ""
+    return sz_engine.search_by_attributes(attributes, flags, search_profile)

examples/docs/using_sz_engine.py

@@ -0,0 +1,7 @@
+from senzing import SzEngine, SzEngineFlags
+
+
+def perform_senzing_search(sz_engine: SzEngine, attributes: str) -> str:
+    flags = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS
+    search_profile = ""
+    return sz_engine.search_by_attributes(attributes, flags, search_profile)

examples/helpers/setup_senzing.py

@@ -23,12 +23,10 @@
 
 def get_sz_abstract_factory() -> SzAbstractFactory:
     """Example AbstractFactory"""
-
     try:
         result = SzAbstractFactoryCore(INSTANCE_NAME, SETTINGS)
     except SzError as err:
         print(f"\nERROR: {err}\n")
-
     return result
 
 

makefiles/linux.mk

@@ -71,6 +71,7 @@ test-osarch-specific:
 	$(info --- Test examples using pytest -------------------------------------)
 	@$(activate-venv); pytest \
 		examples/misc/ \
+		examples/docs/ \
 		examples/extras/ \
 		examples/szabstractfactory/ \
 		examples/szconfig/ \