Docs fixes. Prep for v0.12.1 release

Kintyre · Oct 4, 2023 · 11e0cca · 11e0cca
1 parent acb1de5
commit 11e0cca
Show file tree

Hide file tree

Showing 11 changed files with 41 additions and 38 deletions.
diff --git a/docs/source/api/ksconf.commands.rst b/docs/source/api/ksconf.commands.rst
@@ -4,6 +4,14 @@ ksconf.commands package
 Submodules
 ----------
 
+ksconf.commands.attr module
+---------------------------
+
+.. automodule:: ksconf.commands.attr
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 ksconf.commands.check module
 ----------------------------
 
@@ -36,14 +44,6 @@ ksconf.commands.filter module
    :undoc-members:
    :show-inheritance:
 
-ksconf.commands.getvalue module
--------------------------------
-
-.. automodule:: ksconf.commands.getvalue
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 ksconf.commands.merge module
 ----------------------------
 

diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
@@ -29,7 +29,7 @@ Ksconf 0.12
    In many cases, this really isn't a new dependency, since pluggy requires it as well.
 
 
-Ksconf v0.12.1 (DRAFT)
+Ksconf v0.12.1 (2023-10-03)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 *  Introducing :ref:`ksconf_cmd_attr-get` and :ref:`ksconf_cmd_attr-set` - the newest and simplest ksconf commands ever!
@@ -39,11 +39,12 @@ Ksconf v0.12.1 (DRAFT)
    This can be used to find props with a specific ``KV_MODE``, find saved search containing a specific search command, or list indexes not using ``volume:`` designation.
    See the :ref:`ksconf_cmd_filter` docs for example usage.
 *  Add ``--in-place`` processing behavior for :ref:`ksconf_cmd_merge` to simplify the process of merging new content into an existing conf file.
-*  Fixed documentation generation bug that prevented command line options from showing up in the docs.
+*  Docs Improvements:
+   *  Fixed documentation generation bug that prevented command line options from showing up in the per-command doc pages.  (Broken since v0.10)
+   *  Fixed docs embedded in the Splunk app (and possibly causing some other display issues on the main rtd site)
 *  Fixed some CLI file handling bug that resulted in broken use of ``-`` (stdin) and/or fancy shell commands involving ``<(some command)`` syntax, which can be a helpful trick to reduce the number of temporary files.
 
 
-
 Ksconf v0.12.0 (2023-09-27)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/docs/source/cmd_attr-get.rst b/docs/source/cmd_attr-get.rst
@@ -25,7 +25,7 @@ Show the version of the Splunk AWS technology addon:
 
 
 Fetch the search string for the "Internal Server Errors" search in the from my_app.
-The search is saved to a text file without any metadata or line continuation markers (trailing ```\\`` characters.)
+The search is saved to a text file without any metadata or line continuation markers (trailing ``\`` characters.)
 Note that ``kconf merge`` is used here to ensure that the "live" version of the search is shown, so ``local`` will be used if present, otherwise ``default`` will be shown.
 
 ..  code-block:: sh

diff --git a/docs/source/cmd_attr-set.rst b/docs/source/cmd_attr-set.rst
@@ -42,10 +42,13 @@ Rewrite a saved search to match the new cooperate initiative to relabel all "CRI
 
     ..  code-block:: sh
 
-        printf '[drop_field(1)]\ndefinition=| fields - $field$\nargs=field\niseval=0\n' | ksconf merge --in-place --target macros.conf -
+        printf '[drop_field(1)]\ndefinition=| fields - $field$\nargs=field\niseval=0\n' \
+            | ksconf merge --in-place --target macros.conf -
+
 
         # which is identical to:
-        ksconf merge --in-place --target macros.conf <(printf '[drop_field(1)]\ndefinition=| fields - $field$\nargs=field\niseval=0\n')
+        ksconf merge --in-place --target macros.conf \
+            <(printf '[drop_field(1)]\ndefinition=| fields - $field$\nargs=field\niseval=0\n')
 
     Of course, neither of these are super easy to read.  If your content is static, then an easy answer it to use a static conf file.
     However, at some point it may be easier to just edit these using Python where any arbitrary level of complexity is possible.
@@ -69,7 +72,8 @@ Rewrite a saved search to match the new cooperate initiative to relabel all "CRI
                     if not conf_attr_boolean(conf[report].get("disabled", "0")):
                         # Update enabled search
                         search = conf[report].get("search", "")
-                        conf[report]["search"] = search.replace("cisco:old-understood-tech", "cisco:new-fangled-tech")
+                        conf[report]["search"] = search.replace("cisco:old-understood-tech",
+                                                                "cisco:new-fangled-tech")
                         conf[report]["description"] = f"We did an update.\n Old description: {conf[report].get('description', '')}"
 
     ..  Yes, we need an API intro for simple use cases like this.  For now, I guess this is it!?!
diff --git a/docs/source/cmd_merge.rst b/docs/source/cmd_merge.rst
@@ -9,11 +9,10 @@ ksconf merge
     :path: merge
     :nodefault:
 
-    --in-place: @after
-
-    The ``--in-place`` option was added in v0.12.1.
-    In earlier version of ksconf, and move forward, this same behavior can be accomplished by simply listing the target twice.
-    Once as in the ``--target`` option, and then a second time as the first CONF file.
+    --in-place -i : @after
+        The ``--in-place`` option was added in v0.12.1.
+        In earlier version of ksconf, and moving forward, this same behavior can be accomplished by simply listing the target twice.
+        Once as in the ``--target`` option, and then a second time as the first CONF file.
 
 
 Examples

diff --git a/docs/source/common b/docs/source/common
@@ -1,5 +1,4 @@
 
-
 .. External resources
 
 ..  _GitHub Releases: https://github.com/Kintyre/ksconf/releases

diff --git a/ksconf/commands/attr.py b/ksconf/commands/attr.py
@@ -41,12 +41,12 @@ class AttrGetCmd(KsconfCmd):
     maturity = "beta"
 
     def register_args(self, parser):
-        parser.add_argument("conf", metavar="FILE", nargs="+",
+        parser.add_argument("conf", nargs="+",
                             default=["-"],
                             help="Input file to sort, or standard input."
                             ).completer = conf_files_completer
 
-        parser.add_argument("--stanza", "-s", metavar="STANZA", required=True,
+        parser.add_argument("--stanza", "-s", required=True,
                             help="Name of the conf file stanza to retrieve.")
         parser.add_argument("--attribute", "--attr", "-a",
                             metavar="ATTR", required=True,
@@ -59,7 +59,7 @@ def register_args(self, parser):
                             help="Reduce the amount of output stderr")
         '''
 
-        parser.add_argument("-o", "--output", metavar="FILE",
+        parser.add_argument("-o", "--output",
                             type=argparse.FileType('w'), default=self.stdout,
                             help="File where the filtered results are written.  "
                                  "Defaults to standard out.")
@@ -88,7 +88,8 @@ def run(self, args):
                 try:
                     value = stanza[args.attribute]
                 except KeyError:
-                    self.stderr.write(f"File {conf} does not have {args.attribute} in stanza [{args.stanza}]\n")
+                    self.stderr.write(f"File {conf} does not have {args.attribute} "
+                                      f"in stanza [{args.stanza}]\n")
                     return EXIT_CODE_CONF_NO_DATA_MATCH
             args.output.write(f"{value}\n")
             args.output.flush()
@@ -110,16 +111,16 @@ class AttrSetCmd(KsconfCmd):
     maturity = "beta"
 
     def register_args(self, parser):
-        parser.add_argument("conf", metavar="FILE",
+        parser.add_argument("conf",
                             help="Configuration file to update."
                             ).completer = conf_files_completer
-        parser.add_argument("--stanza", "-s", metavar="STANZA", required=True,
+        parser.add_argument("--stanza", "-s", required=True,
                             help="Name of the conf file stanza to set.")
         parser.add_argument("--attribute", "--attr", "-a",
                             metavar="ATTR", required=True,
                             help="Name of the conf file attribute to set.")
 
-        parser.add_argument("value", metavar="VALUE",
+        parser.add_argument("value",
                             help="Value to apply to the conf file.  Note that this can be a raw "
                             "text string, or the name of the file, or an environment variable")
 

diff --git a/ksconf/commands/merge.py b/ksconf/commands/merge.py
@@ -1,5 +1,5 @@
 """
-SUBCOMMAND:  ``ksconf merge --target=<CONF> <CONF> [ <CONF-n> ... ]``
+SUBCOMMAND:  ``ksconf merge --target=<TARGET_CONF> <CONF> [ <CONF-n> ... ]``
 
 Usage example:
 
@@ -29,13 +29,13 @@ class MergeCmd(KsconfCmd):
     maturity = "stable"
 
     def register_args(self, parser):
-        parser.add_argument("conf", metavar="FILE", nargs="+",
+        parser.add_argument("conf", nargs="+",
                             help="The source configuration file(s) to collect settings from."
                             ).completer = conf_files_completer
-        parser.add_argument("--target", "-t", metavar="FILE",
+        parser.add_argument("--target", "-t",
                             type=ConfFileType("r+", "none", parse_profile=PARSECONF_STRICT),
                             default=ConfFileProxy("<stdout>", "w", self.stdout), help=dedent("""\
-            Save the merged configuration files to this target file.
+            Destination file for merged configurations.
             If not provided, the merged conf is written to standard output.""")
                             ).completer = conf_files_completer
 
@@ -46,9 +46,9 @@ def register_args(self, parser):
 
         parser.add_argument("--in-place", "-i", default=False, action="store_true",
                             help=dedent("""
-            Enable in-place update mode.  When selected, the target file will also be considered as
-            the base of the merge operation.  All conf files will be merged with target.  When disabled,
-            any existing content within target is ignored and overwritten."""))
+            Enable in-place update mode.  When selected, the TARGET file will also be considered as
+            the base of the merge operation.  All CONF files will be merged with TARGET.
+            When disabled, any existing content within TARGET is ignored and overwritten."""))
 
         parser.add_argument("--dry-run", "-D", default=False, action="store_true", help=dedent("""\
             Enable dry-run mode.

diff --git a/ksconf/commands/restexport.py b/ksconf/commands/restexport.py
@@ -107,7 +107,7 @@ class RestExportCmd(KsconfCmd):
 
     """)
     format = "manual"
-    maturity = "beta"
+    maturity = "deprecated"
 
     def register_args(self, parser: ArgumentParser):
         parser.add_argument("conf", metavar="CONF", nargs="+",

diff --git a/ksconf/conf/merge.py b/ksconf/conf/merge.py
@@ -4,7 +4,6 @@
 import shutil
 import sys
 from copy import deepcopy
-from os import fspath
 from typing import List
 
 from ksconf.commands import ConfFileProxy

diff --git a/ksconf/conf/parser.py b/ksconf/conf/parser.py
@@ -530,7 +530,7 @@ class update_conf:
     :param dict profile:  Parsing settings and strictness profile.
     :param str encoding:  encoding to use for file operations.
     :param bool make_missing:  When true, a new blank configuration file will be created
-                               with the updates rather than raising an exception.
+                               if ``conf_path`` is missing, otherwise an exception will be raised.
     """
 
     def __init__(self, conf_path: PathType,