bskinn · bskinn · May 22, 2024 · Nov 29, 2022 · Nov 29, 2022 · Dec 14, 2022
diff --git a/.github/workflows/ci_tests.yml b/.github/workflows/ci_tests.yml
@@ -4,18 +4,18 @@ on: push
 
 jobs:
   all_checks:
-    name: Run all tests, lints, etc. (Python 3.10)
+    name: Run all tests, lints, etc. (Python 3.11)
     runs-on: ubuntu-latest
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
 
     steps:
     - name: Check out repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Install Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.11'
         cache: 'pip'
         cache-dependency-path: |
           requirements-ci.txt
@@ -63,15 +63,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ['3.7', '3.8', '3.9', '3.11']
+        python: ['3.8', '3.9', '3.10', '3.12']
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
 
     steps:
     - name: Check out repo
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Install Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python }}
         cache: 'pip'

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,8 +3,32 @@
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
-and this project strives to adhere to
-[Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+and this project follows an extension of
+[Semantic Versioning](http://semver.org/spec/v2.0.0.html), where a bump in a
+fourth number represents an administrative maintenance release with no code
+changes.
+
+### [2.3.1.1] - 2024-05-21
+
+#### Tests
+
+  * Update test machinery for the shell examples in the README, downstream of
+    the conversion to Markdown ([#289]).
+
+#### Administrative
+
+  * Added formal support for Python 3.12.
+
+  * Removed formal support for Python 3.7, which is end-of-life.
+
+  * Bump `checkout` and `setup-python` GitHub Actions versions ([#289]).
+
+  * Convert README from reST to Markdown ([#289], fixes [#287]).
+
+  * Fix some broken/redirecting docs links ([#289]).
+
+  * Adjust `flake8` configuration to account for some new lint warnings/errors
+    ([#289]).
 
 
 ### [2.3.1] - 2022-11-29
@@ -534,3 +558,7 @@ and this project strives to adhere to
  * Programmatic conversion via API is available, but
    potentially buggy due to poor segregation of cmdline
    behaviors. This is to be fixed.
+
+
+[#287]: https://github.com/bskinn/sphobjinv/issues/287
+[#289]: https://github.com/bskinn/sphobjinv/pull/289
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,8 +5,8 @@ Thanks for your interest in contributing to `sphobjinv`!
 The aim of this document is to provide the information you need
 to get started smoothly on a contribution.
 
-If you have any questions, please drop me a line on Twitter
-([@btskinn](https://twitter.com/btskinn)) or open an
+If you have any questions, please drop me a line on Mastodon
+([@btskinn@fosstodon.org](https://fosstodon.org/@btskinn)) or open an
 [issue](https://github.com/bskinn/sphobjinv/issues).
 
 
@@ -38,12 +38,12 @@ $ git clone https://github.com/{you}/sphobjinv
 ```
 
 Then, create a virtual environment for the project, in whatever location you
-prefer. Any Python interpreter 3.7+ *should* work fine.
+prefer. Any Python interpreter 3.8+ *should* work fine.
 
 I prefer to use `virtualenv` and create in `./env`:
 
 ```
-$ python3.10 -m virtualenv env --prompt="sphobjinv"
+$ python3.11 -m virtualenv env --prompt="sphobjinv"
 ```
 
 Activate the environment:
@@ -153,8 +153,8 @@ Note that while [`tox`](https://tox.wiki/en/latest/) *is* configured for the
 project, it is **not** set up to be an everyday test runner. Instead, it's used
 to execute an extensive matrix of test environments checking for the
 compatibility of different Python and dependency versions. You can run it if you
-want, but you'll need working versions of all of Python 3.7 through 3.11
-installed and on `PATH` as `python3.7`, `python3.8`, etc. The nonlocal test
+want, but you'll need working versions of all of Python 3.8 through 3.12
+installed and on `PATH` as `python3.8`, `python3.9`, etc. The nonlocal test
 suite is run for each `tox` environment, so it's best to use at most two
 parallel sub-processes to avoid oversaturating your network bandwidth; e.g.:
 
@@ -250,7 +250,7 @@ with `make linkcheck`.
 Both Github Actions and Azure Pipelines are set up for the project, and should
 run on any forks of the repository.
 
-Github Actions runs the test suite on Linux for Python 3.7 through 3.11, as well
+Github Actions runs the test suite on Linux for Python 3.8 through 3.12, as well
 as the `flake8` lints and the Sphinx doctests and link-validity testing, and is
 configured to run on all commits. The workflow can be skipped per-commit by
 including `[skip ci]` in the commit message.

diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2022 Brian Skinn and community contributors
+Copyright (c) 2016-2024 Brian Skinn and community contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,5 +1,5 @@
 include AUTHORS.md CHANGELOG.md CONTRIBUTING.md LICENSE.txt pyproject.toml
-include README.rst requirements-dev.txt requirements-flake8.txt tox.ini
+include README.md requirements-dev.txt requirements-flake8.txt tox.ini
 
 graft src/sphobjinv/_vendored/fuzzywuzzy
 

diff --git a/README.md b/README.md
@@ -0,0 +1,211 @@
+## sphobjinv: Manipulate and inspect Sphinx objects.inv files
+
+
+#### Current Development Version
+
+[![GitHub Workflow Status][workflow badge]][workflow link target]
+[![Codecov Coverage][codecov badge]][codecov target]
+
+#### Most Recent Stable Release
+
+[![PyPI Version][pypi badge]][pypi link target]
+![Python Versions][python versions badge]
+
+#### Info
+
+[![ReadTheDocs status][readthedocs badge]][readthedocs link target]
+[![gitter chat][gitter badge]][gitter link target]
+
+[![MIT License][license badge]][license link target]
+[![black formatted][black badge]][black link target]
+[![PePY stats][pepy badge]][pepy link target]
+
+----
+
+### Using Sphinx?
+
+#### Having trouble writing cross-references?
+
+`sphobjinv` (short for '**sph**inx **obj**ects.**inv**') can help!
+
+The syntax required for a functional Sphinx cross-reference is highly
+non-obvious in many cases. Sometimes Sphinx can guess correctly what
+you mean, but it's pretty hit-or-miss.  The best approach is to provide
+Sphinx with a completely specified cross-reference, and that's where
+`sphobjinv` comes in.
+
+After a `pip install sphobjinv` (or `pipx install sphobjinv`), find the
+documentation set you want to cross-reference into, and pass it to
+`sphobjinv suggest`.
+
+For internal cross-references, locate `objects.inv` within `build/html`:
+
+```none
+$ sphobjinv suggest doc/build/html/objects.inv as_rst -st 58
+
+------------------------------------------------
+
+Cannot infer intersphinx_mapping from a local objects.inv.
+
+------------------------------------------------
+
+Project: sphobjinv
+Version: 2.3
+
+220 objects in inventory.
+
+------------------------------------------------
+
+11 results found at/above current threshold of 58.
+
+
+  Name                                                Score
+---------------------------------------------------  -------
+:py:property:`sphobjinv.data.SuperDataObj.as_rst`      60
+:py:class:`sphobjinv.cli.parser.PrsConst`              59
+:py:class:`sphobjinv.data.DataFields`                  59
+:py:class:`sphobjinv.data.DataObjBytes`                59
+:py:class:`sphobjinv.data.DataObjStr`                  59
+:py:class:`sphobjinv.data.SuperDataObj`                59
+:py:class:`sphobjinv.enum.HeaderFields`                59
+:py:class:`sphobjinv.enum.SourceTypes`                 59
+:py:function:`sphobjinv.fileops.writebytes`            59
+:py:function:`sphobjinv.fileops.writejson`             59
+:py:class:`sphobjinv.inventory.Inventory`              59
+```
+
+The `-s` argument in the above shell command indicates to print the
+`fuzzywuzzy` match score along with each search result, and `-t 50`
+changes the reporting threshold for the match score.
+
+For external references, find the API documentation wherever it lives on
+the web, and pass `sphobjinv suggest` a URL from within the documentation set
+with the `--url/-u` flag. For example, say I need to know how to
+cross-reference the `linspace` function from numpy (see
+[here][numpy linspace]):
+
+```none
+$ sphobjinv suggest https://numpy.org/doc/1.26/reference/index.html linspace -su
+
+Attempting https://numpy.org/doc/1.26/reference/index.html ...
+  ... no recognized inventory.
+Attempting "https://numpy.org/doc/1.26/reference/index.html/objects.inv" ...
+  ... HTTP error: 404 Not Found.
+Attempting "https://numpy.org/doc/1.26/reference/objects.inv" ...
+  ... HTTP error: 404 Not Found.
+Attempting "https://numpy.org/doc/1.26/objects.inv" ...
+  ... inventory found.
+
+----------------------------------------------------------------------------------
+
+The intersphinx_mapping for this docset is LIKELY:
+
+  (https://numpy.org/doc/1.26/, None)
+
+----------------------------------------------------------------------------------
+
+Project: NumPy
+Version: 1.26
+
+8152 objects in inventory.
+
+----------------------------------------------------------------------------------
+
+8 results found at/above current threshold of 75.
+
+  Name                                                           Score
+--------------------------------------------------------------  -------
+:py:function:`numpy.linspace`                                     90
+:py:method:`numpy.polynomial.chebyshev.Chebyshev.linspace`        90
+:py:method:`numpy.polynomial.hermite.Hermite.linspace`            90
+:py:method:`numpy.polynomial.hermite_e.HermiteE.linspace`         90
+:py:method:`numpy.polynomial.laguerre.Laguerre.linspace`          90
+:py:method:`numpy.polynomial.legendre.Legendre.linspace`          90
+:py:method:`numpy.polynomial.polynomial.Polynomial.linspace`      90
+:std:doc:`reference/generated/numpy.linspace`                     90
+```
+
+**NOTE** that the results from `sphobjinv suggest` are printed using the
+longer *block directives*, whereas cross-references must be composed using the
+*inline directives*. Thus, the above `linspace()` function must be
+cross-referenced as ``` :func:`numpy.linspace` ``` , **not**
+``` :function:`numpy.linspace` ```.
+
+**Need to edit an inventory after it's created, or compose one from scratch?**
+
+`sphobjinv` can help with that, too.
+
+`objects.inv` files can be decompressed to plaintext at the commandline:
+
+```none
+$ sphobjinv convert plain -o doc/build/html/objects.inv doc/scratch/
+Conversion completed.
+'...objects.inv' converted to '...objects.txt' (plain).
+```
+
+JSON output is supported (`sphobjinv convert json ...`), and
+inventories can be re-compressed to the
+partially-zlib-compressed form that `intersphinx` reads
+(`sphobjinv convert zlib ...`).
+
+Alternatively, `sphobjinv` exposes an API to enable automation of
+inventory creation/modification:
+
+```python
+>>> import sphobjinv as soi
+>>> inv = soi.Inventory('doc/build/html/objects.inv')
+>>> print(inv)
+<Inventory (fname_zlib): sphobjinv v2.3, 220 objects>
+>>> inv.project
+'sphobjinv'
+>>> inv.version
+'2.3'
+>>> inv.objects[0]
+DataObjStr(name='sphobjinv.cli.convert', domain='py', role='module', priority='0', uri='cli/implementation/convert.html#module-$', dispname='-')
+
+```
+
+The API also enables straightforward re-export of an inventory, for subsequent
+use with `intersphinx` cross-references. See [the docs][soi docs inv export] for
+more details.
+
+----
+
+Full documentation is hosted at [Read The Docs][readthedocs link target].
+
+Available on [PyPI][pypi link target] (`pip install sphobjinv`).
+
+Source on [GitHub][github repo]. Bug reports and feature requests are welcomed
+at the [Issues][github issue tracker] page there.
+
+Copyright (c) Brian Skinn 2016-2024
+
+The `sphobjinv` documentation (including docstrings and README) is licensed
+under a [Creative Commons Attribution 4.0 International License][cc-by 4.0]
+(CC-BY). The `sphobjinv` codebase is released under the [MIT License]. See
+[`LICENSE.txt`][license link target] for full license terms.
+
+
+[black badge]: https://img.shields.io/badge/code%20style-black-000000.svg
+[black link target]: https://github.com/psf/black
+[cc-by 4.0]: http://creativecommons.org/licenses/by/4.0/
+[codecov badge]: https://codecov.io/gh/bskinn/sphobjinv/branch/main/graph/badge.svg
+[codecov target]: https://codecov.io/gh/bskinn/sphobjinv
+[soi docs inv export]: http://sphobjinv.readthedocs.io/en/latest/api_usage.html#exporting-an-inventory
+[github issue tracker]: https://github.com/bskinn/sphobjinv/issues
+[github repo]: https://github.com/bskinn/sphobjinv
+[gitter badge]: https://badges.gitter.im/sphobjinv/community.svg
+[gitter link target]: https://gitter.im/sphobjinv/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+[license badge]: https://img.shields.io/github/license/mashape/apistatus.svg
+[license link target]: https://github.com/bskinn/sphobjinv/blob/stable/LICENSE.txt
+[mit license]: https://opensource.org/licenses/MIT
+[numpy linspace]: https://numpy.org/doc/1.26/reference/generated/numpy.linspace.html
+[pepy badge]: https://pepy.tech/badge/sphobjinv/month
+[pepy link target]: https://pepy.tech/project/sphobjinv?versions=2.0.1&versions=2.1&versions=2.2.2&versions=2.3&versions=2.3.1
+[pypi badge]: https://img.shields.io/pypi/v/sphobjinv.svg?logo=pypi]
+[pypi link target]: https://pypi.org/project/sphobjinv
+[python versions badge]: https://img.shields.io/pypi/pyversions/sphobjinv.svg?logo=python
+[readthedocs badge]: https://img.shields.io/readthedocs/sphobjinv/latest.svg
+[readthedocs link target]: http://sphobjinv.readthedocs.io/en/latest/
+[workflow badge]: https://img.shields.io/github/actions/workflow/status/bskinn/sphobjinv/ci_tests.yml?logo=github&branch=main
+[workflow link target]: https://github.com/bskinn/sphobjinv/actions