Command-Line Usage: `sphobjinv-textconv`

sphobjinv-textconv is intentionally implemented with very narrow functionality, focused on simplifying use of sphobjinv as a Git “textconv”, which is a mechanism for rendering binary files in a diff-able text format. There are many examples of clever application of textconv in the wild.

Ultimately, a textconv requires three things:

A utility that takes in a file path as a single positional argument and emits a plaintext representation to stdout, such as sphobjinv-textconv.
An entry somewhere in Git config (system, user-global, per-repo, etc.) declaring a “diff driver” set up to use that utility as its textconv. Example:
```
[diff "objects_inv"]
        textconv = sphobjinv-textconv
```
Note that the utility must be on path in all contexts where you wish to use it as a textconv.
An entry somewhere in .gitattributes (system, user-global, per-repo, etc.) that associates a particular file or glob pattern with the diff driver. Example:
```
*.inv diff=objects_inv
```

With sphobjinv-textconv configured in this fashion as a textconv for Sphinx inventory files, the following should all yield nearly the same output.

Using sphobjinv convert:

$ sphobjinv convert plain objects_pdfminer.inv -
 
 
# Sphinx inventory version 2
# Project: pdfminer-docs
# Version: 0
# The remainder of this file is compressed using zlib.
genindex std:label -1 genindex.html Index
index std:doc -1 index.html pdfminer docs
modindex std:label -1 py-modindex.html Module Index
pdfminer_index std:doc -1 pdfminer_index.html PDFMiner
programming std:doc -1 programming.html Programming with PDFMiner
search std:label -1 search.html Search Page

Using sphobjinv-textconv (note the absence of blank lines between the shell invocation and the inventory contents):

$ sphobjinv-textconv objects_pdfminer.inv
# Sphinx inventory version 2
# Project: pdfminer-docs
# Version: 0
# The remainder of this file is compressed using zlib.
genindex std:label -1 genindex.html Index
index std:doc -1 index.html pdfminer docs
modindex std:label -1 py-modindex.html Module Index
pdfminer_index std:doc -1 pdfminer_index.html PDFMiner
programming std:doc -1 programming.html Programming with PDFMiner
search std:label -1 search.html Search Page

Using git show --textconv (with the textconv set on-the-fly so that it will render correctly in ReadTheDocs builds):

Usage

$ sphobjinv-textconv --help
usage: sphobjinv-textconv [-h] [-v] infile

Emit the plaintext of the local Sphinx inventory at 'infile' to stdout.

...

Positional Arguments

infile: Path to file to be emitted to stdout in plaintext.

Flags

-h, --help: Display help message and exit.

-v, --version: Display brief package version information and exit.

Added in version 2.4.

Command-Line Usage: sphobjinv-textconv

Command-Line Usage: `sphobjinv-textconv`