Docs & cleanups

- Expand docs for 'ksconf package'.  Added a listing of currently supported
  variable substitutions.
- Fixed a few more regexes to use raw strings, whoops.
- Fixed random spelling mistakes
- Add notes about GitHub Discussions and removed link to #ksconf Slack channel
  as link appears broken.

docs/source/cmd_minimize.rst

@@ -60,7 +60,7 @@ You can use :ref:`ksconf_cmd_merge` to reverse the effect of minimize by running
 
     ksconf merge default/inputs.conf local/inputs.conf
 
-..  Confirm this works before adversizing:  ksconf merge --target=local/inputs.conf default/inputs.conf local/inputs.conf
+..  Confirm this works before advertising:  ksconf merge --target=local/inputs.conf default/inputs.conf local/inputs.conf
 ..  It's unclear if we allow --target to be the same file as one of the inputs....  Most likely this currently causes things to melt...but it shouldn't
 
 Additional capabilities
@@ -70,7 +70,7 @@ For special cases, the ``--explode-default`` mode reduces duplication between en
 then additionally reduces duplication between individual stanzas and default entries.
 Typically you only need this mode if your dealing with a conf file that's been fully expanded to include all the layers,
 which doesn't happen under normal circumstances.
-This does happen anytime you download a stanza from a REST endpoint or munge together output from ``btool list``.
+This does happen anytime you download a stanza from a REST endpoint or munged together output from ``btool list``.
 If you've ever done this with ``savedsearches.conf`` stanzas, you'll be painfully aware of how massive they are!
 This is the exact use case that ``--explode-default`` was written for.
 

docs/source/cmd_package.rst

@@ -12,10 +12,49 @@ ksconf package
     :nodefault:
 
 
+Variables
+---------
+
+The following variables are currently available for use during package building.
+These are referenced using the ``{{var}}`` syntax.
+See the implementation in :py:class:`~ksconf.package.AppVarMagic` if you'd like to contribute additional variables.
+
+Supported Variables
+
+    ==================  =========   ============================================================
+    Variable            Source      Notes
+    ==================  =========   ============================================================
+    ``build``           app.conf    Get ``build`` from ``[install]`` in ``app.conf``
+    ``version``         app.conf    Get ``version`` from ``[launcher]`` in ``app.conf``
+    ``git_tag``         git         Run ``git describe --tags --always --dirty``
+    ``git_latest_rev``  git         Run ``git log -n1 --pretty=format:%h -- .``
+    ``git_head``        git         Run ``git rev-parse --short HEAD``
+    ==================  =========   ============================================================
+
+
 
 Example
 -------
 
 ..  code-block:: sh
 
     ksconf package -f my_app.tgz MyApp
+
+
+A more realistic example where the version number in ``app.conf`` is managed by some external process, possibly a tool like ``bumpversion``.
+
+..  code-block:: sh
+
+    bumpversion minor
+    ksconf package -f dist/my_app-{{version}}.tgz MyApp --release-file=.artifact
+    echo "Build complete, upload $(<.artifact) to SplunkBase"
+
+This will output a message like: ``Build complete, upload dist/my_app-1.2.3.tgz to SplunkBase``
+
+And of course this workflow could be further automated using Splunkbase API calls.
+
+
+See also
+--------
+
+More sophisticated builds can be achieved using the :py:class:`~ksconf.builder.core.BuildManager`

docs/source/contact_us.rst

@@ -7,7 +7,8 @@ If you have questions, concerns, ideas about the product or how to make it bette
 
 Here are some ways to get in contact with us and other KSCONF users:
 
- -  Chat about `#ksconf <https://slack.com/app_redirect?channel=CDVT14KUN>`_ on Splunk's `Slack <https://splunk-usergroups.slack.com>`_ channel.
+ -  Chat about ``#ksconf`` on Splunk's `Slack <https://splunk-usergroups.slack.com>`_ channel.
+ -  Discuss features or ask general questions in `GitHub discussions <https://github.com/Kintyre/ksconf/discussions>`_.  **This is new**, please drop by and let us know if this is helpful or not.
  -  Email us at hello@kintyre.co for general inquiries, if you're interested in commercial support, or would like to fund new features.
  -  Ask a question on
 

ksconf/builder/__init__.py

@@ -99,7 +99,7 @@ def run(self, *args):
 def default_cli(build_manager, build_funct, argparse_parents=()):
     # args: (BuildManager, Callable[BuildStep, argparse.Namespace], List[argparse.ArgumentParser]
     """
-    This is the function you stick in the:  if __name__ == '__main__' section of your code :-)
+    This is the function you stick in the:  ``if __name__ == '__main__'`` section of your code :-)
 
     Pass in a BuildManager instance, and a callback function.  The callback function must accept
     (steps, args).  If you have need for custom arguments, you can add them to your own

ksconf/builder/cache.py

@@ -22,8 +22,8 @@ class FileSet(object):
     Currently the fingerprint is only a SHA256 hash.
 
     Two constructore are provided for building an instance from either file that
-    live on the filesystem, via `:method:from_filesystem()` or from a persisted
-    cached record aviable from the `:method:from_cache()`.
+    live on the filesystem, via :py:meth:`from_filesystem` or from a persisted
+    cached record aviable from the :py:meth:`from_cache`.
     The filesystem version actively reads all inputs files at object creation
     time, so this can be costly, especially if repeated.
     """

ksconf/layer.py

@@ -116,7 +116,7 @@ class LayerConfig(object):
     def __init__(self):
         # Set defaults
         self.follow_symlink = False
-        self.blacklist_files = re.compile("\.(bak|swp)$")
+        self.blacklist_files = re.compile(r"\.(bak|swp)$")
         self.blacklist_dirs = {".git"}
 
 
@@ -328,8 +328,8 @@ def __init__(self, path):
             super(DotDLayerRoot.MountDotD, self).__init__(path)
     '''
 
-    mount_regex = re.compile("(?P<realname>[\w_.-]+)\.d$")
-    layer_regex = re.compile("(?P<layer>\d\d-[\w_.-]+)")
+    mount_regex = re.compile(r"(?P<realname>[\w_.-]+)\.d$")
+    layer_regex = re.compile(r"(?P<layer>\d\d-[\w_.-]+)")
 
     def __init__(self, config=None):
         super(DotDLayerRoot, self).__init__(config)
@@ -388,17 +388,3 @@ def list_layers(self):
     def order_layers(self):
         # Sort based on layer name (or other sorting priority:  00-<name> to 99-<name>
         self._layers.sort(key=lambda l: l.name)
-
-
-def run_oldshool(args):
-
-    combined19 = DirectLayerRoot()
-    # Take CLI args and apply to root
-    for src in args.source:
-        combined19.add_layer(src)
-
-    layers = list(combined19.list_layers())
-    print("Given layers:  {}".format(layers))
-
-    files = combined19.list_files()
-    print("Files:  {}", files)

ksconf/package.py

@@ -122,14 +122,18 @@ def update_app_conf(self, version=None, build=None):
                 if value:
                     if stanza not in conf:
                         conf[stanza] = {}
-                    self.output.write("\tUpdate app.conf:  [{}] {} = {}\n".format(stanza, attr, value))
+                    self.output.write("\tUpdate app.conf:  [{}] {} = {}\n"
+                                      .format(stanza, attr, value))
                     conf[stanza][attr] = value
 
     def make_archive(self, filename):
+        """ Create a compressed tarball of the build directory.
+        """
+        # type: (str) -> None
         # if os.path.isfile(filename):
         #    raise ValueError("Destination file already exists:  {}".format(filename))
 
-        # Doh:  version 3.2: Added support for the context management protocol.  (need to wait to use it)
+        # Python 3.2+, use context manager
         spl = tarfile.open(filename, mode="w:gz")
         spl.add(self.app_dir, arcname=self.app_name)
         spl.close()