ksconf.version expose public names

- Use simple public names in ksconf.version (since the module name is public)
  This makes import fallback techniques simple too,
- Document the best version capturing technique (works across ksconf versions)
- General docs update \w
- Refreshed build example

docs/source/_static/build.py

@@ -48,12 +48,12 @@ def package_spl(step: BuildStep):
     release_name = top_dir / ".release_name"
     # Verbose message
     log("Starting to package SPL file!", VERBOSE)
-    step.run(sys.executable, "-m", "ksconf", "package",
-             "--file", step.dist_path / SPL_NAME,   # Path to created tarball
-             "--app-name", APP_FOLDER,              # Top-level directory name
-             "--block-local",                       # VC build, no 'local' folder
-             "--release-file", str(release_path),
-             ".")
+    step.run_ksconf("package",
+                    "--file", step.dist_path / SPL_NAME,   # Path to created tarball
+                    "--app-name", APP_FOLDER,              # Top-level directory name
+                    "--block-local",                       # VC build, no 'local' folder
+                    "--release-file", str(release_path),
+                    ".")
     # Provide the dist file as a short name too (used by some CI/CD tools)
     path = release_path.read_text()
     short_name = Path(path).name

docs/source/api/ksconf.rst

@@ -13,6 +13,7 @@ Subpackages
    ksconf.builder
    ksconf.commands
    ksconf.conf
+   ksconf.plugins
    ksconf.util
    ksconf.vc
 
@@ -115,6 +116,14 @@ ksconf.setup\_entrypoints module
    :undoc-members:
    :show-inheritance:
 
+ksconf.version module
+---------------------
+
+.. automodule:: ksconf.version
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 ksconf.xmlformat module
 -----------------------
 

docs/source/api_ref.rst

@@ -11,6 +11,8 @@ API Reference
 
     As of right now, the general rule of thumb is this:
     Anything well-covered by the unit tests should be be fairly safe to build on top of, but again, :ref:`ping us <contact_us>`.
+    Also, things used in the `cdillc.splunk`_ Ansible Collection should be fairly safe too.
+    There's a decent bit of back and forth between these two projects driving feature development.
 
 
 ..  commments
@@ -36,3 +38,47 @@ KSCONF API
 
     api/modules
     build_example
+
+
+
+..  _api_ksconf_version:
+
+Version information
+-------------------
+
+For code bases using ksconf, sometimes behaviors have to vary based on ksconf version.
+
+In general, the best approach is to either (1) specify a hard version requirement in a packaging, or (2) if you have to support a wider range of versions use the `EAFP <https://docs.python.org/3.9/glossary.html#term-eafp>`_ approach of asking for forgiveness rather than permission.
+In other words, simply try to import the module or call then method you need and if the modules doesn't exist or the new method argument doesn't exist yet, capture that in an exception.
+
+Other times a direct version number is helpful to evaluate or simply report to the user.
+Here's the approach works across the widest range of ksconf versions:
+
+..  code-block:: python
+
+    try:
+        from ksconf.version import version, version_info
+    except ImportError:
+        from ksconf._version import version
+        # If you need version_info; if not drop this next line
+        version_info = tuple(int(p) if p.isdecimal() else p for p in version.split("."))
+
+
+
+..  note::  Historic version capture
+
+    In ksconf 0.12.0, the suggested method was to simply use:
+
+
+    ..  code-block:: python
+
+        from ksconf import __version__
+
+    This is simple and straight forward.
+    However this no longer works as of version 0.13 and later due to migration to a namespace package and this is no longer viable.
+    Therefore, we recommend approach detailed above.
+
+
+
+
+..  include:: common

docs/source/changelog.rst

@@ -23,17 +23,23 @@ Renames:
 - ``ksconf/commands/__init__.py`` -> ``ksconf/command.py``
 
 
-Ksconf v0.13.3 (2023-10-13)
+Ksconf v0.13.4 (2023-10-13)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**API Changes (only)**:
+
+*  Minor tweaks to :py:mod:`ksconf.version` to use public names instead of dunder names.
+   So ``from ksconf.version import version`` instead of ``from ksconf.version import __version__``.
+   Note that the old names still exist, with no deprecation planned.
+   The api docs were updated to demo the best approach to determine the :ref:`ksconf version <api_ksconf_version>`
 *  Expand :py:class:`~ksconf.app.manifest.AppManifest` class to support file filtering upon manifest creation.
-   Also added some inline docs.
+*  Updated splunk app building example.
 
 
 Ksconf v0.13.3 (2023-10-12)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*  Created a new public interface :ref:py:mod:`ksconf.version`.
+*  Created a new public interface :py:mod:`ksconf.version`.
    This provides a consistent means of getting the version information without any extra modules being loaded, now that ksconf is a namespace package.
    Note that for v0.13.0 - 0.13.2, this was called ``ksconf._ksconf``.
    Hopefully in that short time frame nobody got too attached to that terrible name.

ksconf/version.py

@@ -10,11 +10,19 @@
 
 # _version.py is autogenerated at build time.  But is missing on first call to setup.py
 try:
-    from ._version import build as __build__, vcs_info as __vcs_info__, version as __version__
+    from ._version import build, vcs_info, version
+    version_info = tuple(int(p) if p.isdecimal() else p
+                         for p in version.split("."))
 except ImportError:     # pragma: no cover
-    __version__ = None
-    __build__ = None
-    __vcs_info__ = None
+    version = ""
+    build = None
+    vcs_info = None
+    version_info = ()
+
+# Keeping the private/conventional variables for backwards compatibility
+__version__ = version
+__build__ = build
+__vcs_info__ = vcs_info
 
 
 # Because how do you pick just just ONE?!!
@@ -96,6 +104,7 @@
 |_|\_\___/\___\___/|_| |_|_|
 """)
 
+
 if __name__ == '__main__':
     from ._version import SHELL_VER_VARS
     print(SHELL_VER_VARS)