bskinn · bskinn · Jan 6, 2026 · Aug 29, 2024 · Aug 30, 2024 · Aug 30, 2024
diff --git a/.gitattributes b/.gitattributes
@@ -1,2 +1,3 @@
 tests/resource/objects_mkdoc_zlib0.inv binary
 tests/resource/objects_attrs.txt binary
+*.inv diff=objects_inv
diff --git a/.github/workflows/release_enusre_no_ver_markers.yml b/.github/workflows/release_enusre_no_ver_markers.yml
@@ -0,0 +1,28 @@
+name: 'RELEASE: Check docs source files'
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - ready_for_review
+    branches:
+      - stable
+
+jobs:
+  ver_placeholder_search:
+    name: 'have no ##VER## markers'
+    runs-on: 'ubuntu-latest'
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    if: ${{ !github.event.pull_request.draft }}
+
+    steps:
+    - name: Check out repo
+      uses: actions/checkout@v6
+
+    - name: Error if any markers found
+      run: |
+        grep -ri '#VER#' doc/source && exit 1 || exit 0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,8 +10,21 @@ changes.
 
 ### *Unreleased*
 
+#### Added
+
+  * Add `sphobjinv-textconv` CLI entrypoint ([#331]).
+    * Takes a single required argument, the path to a local inventory file, and
+      emits the plaintext inventory to `stdout`.
+    * The target use-case is as a Git textconv, primarily intended for
+      compressed `objects.inv` files; but, it will work with any valid type of
+      input file.
+
 #### Tests
 
+  * Add tests exercising the new `sphobjinv-textconv` CLI entrypoint ([#331]).
+    * Required generalizing the `run_cmdline_test` fixture so that tests can
+      choose between the core and textconv entrypoints.
+
   * Update `tox` env test matrix for `py310` to `py314` ([#325]).
 
   * Update test path calculations to always be relative to `__file__` ([#325]).
@@ -36,6 +49,9 @@ changes.
 
 #### Internal
 
+  * Add Actions workflow to error on a non-draft release branch if any `#VER#`
+    markers remain in docs source ([#331]).
+
   * Augment `black` and `flake8` `tox` envs to run `--version` first ([#327]).
 
   * Remove `-r requirements-flake.txt` from `requirements-dev.txt` ([#327]).
@@ -57,6 +73,30 @@ changes.
     * This will provide `main` branch CI results for this workflow, for the
       GitHub badge to report.
 
+#### Documentation
+
+  * Dynamically retrieve the current values of `PrsConst.SUGGEST_CONFIRM_LENGTH`
+    and `PrsConst.DEF_THRESH` to define their replaces in `conf.py` ([#331]).
+
+  * Add `cli/textconv.rst` to document the new `sphobjinv-textconv` CLI
+    entrypoint ([#331]).
+
+  * Cull some superfluous replaces in `conf.py` ([#331]).
+
+  * Relocate the 'help' and 'version' CLI usage documentation content to a new
+    'orphan' page ([#331]).
+    * This keeps the content in the `objects.inv`, for completeness, but keeps
+      it off of the docs nav.
+
+  * Revise 'CLI Usage' documentation to incorporate the `sphobjinv-textconv`
+    entrypoint ([#331]).
+
+  * Remove the 'CLI Implementation' "API reference" docs ([#331]).
+    * They're not part of the public API contract, and they don't actually help
+      understand how the CLI is implemented; so, why bother maintaining them?
+    * Also cull the various `replace` directives defined in `conf.py` for these
+      docs.
+
 #### Administrative
 
   * Add formal support for Python 3.14 ([#325]).
@@ -739,3 +779,4 @@ changes.
 [#320]: https://github.com/bskinn/sphobjinv/pull/320
 [#325]: https://github.com/bskinn/sphobjinv/pull/325
 [#327]: https://github.com/bskinn/sphobjinv/pull/327
+[#331]: https://github.com/bskinn/sphobjinv/pull/331
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
@@ -1,7 +1,7 @@
 .. API page
 
-API
-===
+API Reference
+=============
 
 Most (all?) of the objects documented in the below submodules
 are also exposed at the |soi| package root. For example,

diff --git a/doc/source/cli/convert.rst b/doc/source/cli/convert.rst
@@ -1,7 +1,7 @@
 .. Description of convert commandline usage
 
-Command-Line Usage: "convert" Subcommand
-========================================
+Command-Line Usage: ``sphobjinv convert``
+=========================================
 
 .. program:: sphobjinv convert
 

diff --git a/doc/source/cli/implementation/convert.rst b/doc/source/cli/implementation/convert.rst
diff --git a/doc/source/cli/implementation/core.rst b/doc/source/cli/implementation/core.rst
diff --git a/doc/source/cli/implementation/index.rst b/doc/source/cli/implementation/index.rst
diff --git a/doc/source/cli/implementation/load.rst b/doc/source/cli/implementation/load.rst
diff --git a/doc/source/cli/implementation/parser.rst b/doc/source/cli/implementation/parser.rst
diff --git a/doc/source/cli/implementation/paths.rst b/doc/source/cli/implementation/paths.rst
diff --git a/doc/source/cli/implementation/suggest.rst b/doc/source/cli/implementation/suggest.rst
diff --git a/doc/source/cli/implementation/ui.rst b/doc/source/cli/implementation/ui.rst
diff --git a/doc/source/cli/implementation/write.rst b/doc/source/cli/implementation/write.rst
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
@@ -3,23 +3,39 @@
 Command-Line Usage
 ==================
 
-The CLI for |soi| is implemented using two subcommands:
+The primary CLI for |soi| is implemented using two subcommands of the
+``sphobjinv`` entrypoint:
 
-  - A :doc:`convert <convert>` subcommand, which handles conversion of
-    inventories between supported formats (currently zlib-compressed,
+  - ``sphobjinv convert`` (:doc:`docs page <convert>`), which handles conversion
+    of inventories between supported formats (currently zlib-compressed,
     plaintext, and JSON).
-  - A :doc:`suggest <suggest>` subcommand, which provides suggestions for
+  - ``sphobjinv suggest`` (:doc:`docs page <suggest>`), which provides suggestions for
     objects in an inventory matching a desired search term.
 
-More information about the underlying implementation of these subcommands can
-be found :doc:`here <implementation/index>` and in the documentation for the
-:class:`~sphobjinv.inventory.Inventory` object, in particular the
-:meth:`~sphobjinv.inventory.Inventory.data_file` and
-:meth:`~sphobjinv.inventory.Inventory.suggest` methods.
+As of v##VER##, |soi| also provides an auxiliary entrypoint,
+``sphobjinv-textconv`` (:doc:`docs page <textconv>`), which takes one required
+argument: a path to a file on disk. This entrypoint attempts to instantiate an
+|Inventory| with this file and emit its plaintext contents to |stdout| with no
+cosmetic whitespace. The following two invocations are thus nearly synonymous::
 
-Some notes on these CLI docs:
+    $ sphobjinv convert plain path/to/objects.inv -
 
- * CLI docs examples are executed in a sandboxed directory pre-loaded with
+    $ sphobjinv-textconv path/to/objects.inv
+
+(Be sure to note the final hyphen in the first command.) The
+``sphobjinv-textconv`` spelling is less awkward when configuring a Git
+|textconv| to allow rendering diffs of |objects.inv| files in plaintext. See the
+``sphobjinv-textconv`` :doc:`entrypoint documentation <textconv>` for more
+information.
+
+----
+
+Shell examples in the CLI docs execute from within |cour|\ /tests/resource\
+|/cour| unless indicated otherwise.
+
+For Python examples:
+
+ * Examples are executed in a sandboxed directory pre-loaded with
    |cour|\ objects_attrs.inv\ |/cour| (from, e.g.,
    `here <https://github.com/bskinn/sphobjinv/blob/main/
    tests/resource/objects_attrs.inv>`__).
@@ -35,28 +51,10 @@ Some notes on these CLI docs:
  * |cour|\ file_head\ |/cour| is a helper function
    that retrieves the head of a specified file.
 
-
-.. program:: sphobjinv
-
-The options for the parent |soi| command are:
-
-.. option:: -h, --help
-
-    Show help message and exit
-
-.. program-output:: sphobjinv --help
-
-
-.. option:: -v, --version
-
-    Print package version & other info
-
-.. program-output:: sphobjinv --version
-
-
 .. toctree::
     :maxdepth: 1
     :hidden:
 
-    "convert" Mode <convert>
-    "suggest" Mode <suggest>
+    sphobjinv convert <convert>
+    sphobjinv suggest <suggest>
+    sphobjinv-textconv <textconv>
diff --git a/doc/source/cli/soi_root.rst b/doc/source/cli/soi_root.rst
@@ -0,0 +1,26 @@
+:orphan:
+
+.. Description of root soi entrypoint commandline usage
+
+Root "sphobjinv" Entrypoint Usage
+=================================
+
+.. program:: sphobjinv
+
+The following options of the 'root' of the ``sphobjinv`` CLI entrypoint are
+documented in this 'orphan' page so that they will appear in the docset
+`objects.inv` and be available for linking, if needed, but otherwise be hidden
+from the navigation of the documentation.
+
+.. option:: -h, --help
+
+    Show help message and exit
+
+.. program-output:: sphobjinv --help
+
+
+.. option:: -v, --version
+
+    Print package version & other info
+
+.. program-output:: sphobjinv --version
diff --git a/doc/source/cli/suggest.rst b/doc/source/cli/suggest.rst
@@ -1,7 +1,7 @@
 .. Description of suggest commandline usage
 
-Command-Line Usage: "suggest" Subcommand
-========================================
+Command-Line Usage: ``sphobjinv suggest``
+=========================================
 
 .. program:: sphobjinv suggest
 
@@ -82,9 +82,9 @@ If download of JSON files by URL is desirable, please
 
 .. option:: -a, --all
 
-    Display all search results without prompting, regardless of the number of hits.
-    Otherwise, prompt if number of results exceeds
-    :attr:`~sphobjinv.cli.parser.PrsConst.SUGGEST_CONFIRM_LENGTH`.
+    Display all search results without prompting, regardless of the number of
+    hits. Otherwise, prompt for confirmation before displaying the entire result
+    set if count exceeds |cli:SUGGEST_CONFIRM_LENGTH|.
 
 .. option:: -i, --index
 
@@ -99,8 +99,7 @@ If download of JSON files by URL is desirable, please
 .. option:: -t, --thresh <#>
 
     Change the |fuzzywuzzy|_ match quality threshold (0-100; higher values
-    yield fewer results). Default is specified in
-    :attr:`~sphobjinv.cli.parser.PrsConst.DEF_THRESH`.
+    yield fewer results). Current default threshold is |cli:DEF_THRESH|.
 
 .. option:: -u, --url