Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release v2.3.1.1 #293

Merged
merged 49 commits into from
May 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
49 commits
Select commit Hold shift + click to select a range
3fbba4c
Bump version to 2.3.2.dev0
bskinn Nov 29, 2022
1bdd804
Merge branch 'release-2.3.1'
bskinn Nov 29, 2022
009c018
Restore 'name' arg in setup.py
bskinn Dec 14, 2022
4a1e044
Fix GH build badge
bskinn Dec 25, 2022
77bfc4d
Create SECURITY.md
bskinn Dec 26, 2022
fbb8847
Mention priority 0 and 2
pawamoy Aug 28, 2023
af4333e
Update ArchLinux link in index
pawamoy Aug 31, 2023
df27855
Merge pull request #284 from pawamoy/patch-1
bskinn Aug 31, 2023
c67f984
Rename to README.md and start converting
bskinn Apr 20, 2024
24e231e
Point setup.py to the new README.md
bskinn Apr 20, 2024
981f3c5
Try multiline badge blocks
bskinn Apr 25, 2024
e4969e9
Continue converting README
bskinn Apr 25, 2024
0c7202e
Finish converting README
bskinn May 6, 2024
b35f98c
Fix flake8 'qualified name' complaint
bskinn May 6, 2024
3b5ebb7
Bump GHA workflow versions
bskinn May 6, 2024
df62440
Ignore flake8 A005
bskinn May 6, 2024
44116a3
Fix some external URLs
bskinn May 6, 2024
ff726c4
Add Python 3.12, retire Python 3.7
vonschultz May 8, 2024
b80cdf1
Update test_readme.py
bskinn May 9, 2024
254ccbb
Remove unneeded shell text block markers
bskinn May 9, 2024
fa8afcb
Update CHANGELOG
bskinn May 9, 2024
e3a2d33
Merge pull request #289 from bskinn/287-readme-md-convert
bskinn May 10, 2024
23862fd
Merge remote-tracking branch 'upstream/main' into python-versions
vonschultz May 13, 2024
3ab0989
Merge pull request #291 from vonschultz/python-versions
bskinn May 14, 2024
fc42f22
Loosen pagination test
bskinn May 21, 2024
82e7477
Update links out to Sphinx docs
bskinn May 21, 2024
7de5ce1
Remove broken distro refs from index.rst
bskinn May 21, 2024
a1a4859
Update Python ref on customfile.rst
bskinn May 21, 2024
513c3b7
Update README shell examples
bskinn May 21, 2024
4fee280
Remove README shell tests
bskinn May 21, 2024
46243b1
Update syntax.rst Python version
bskinn May 21, 2024
bb645ff
Remove additional wayward --readme
bskinn May 21, 2024
ac52608
Bump Python and dep versions in tox suite
bskinn May 21, 2024
d383f68
Bump primary CI Python version to 3.11
bskinn May 21, 2024
24cb28a
Add trial pyproject.toml
bskinn May 21, 2024
aae6500
Rename trial pyproject.toml to real, and tweak
bskinn May 21, 2024
aa1aa9d
Remove trial pyproject and obsolete setup.cfg
bskinn May 21, 2024
cb4cd74
Switch to README.md in MANIFEST.in
bskinn May 21, 2024
3e43ab2
Bump version to v2.3.2
bskinn May 21, 2024
341c305
Update copyright years
bskinn May 21, 2024
79497f4
Switch social link to Fosstodon
bskinn May 21, 2024
caf4639
Update CHANGELOG for v2.3.2
bskinn May 21, 2024
7842654
Update CONTRIBUTING.md
bskinn May 21, 2024
cf9d3ba
Bump Sphinx to v7.3.7
bskinn May 21, 2024
fa0ec1a
Drop dev Sphinx to 7.1.2
bskinn May 21, 2024
838eccf
Change version bump to 2.3.1.1 and update CHANGELOG
bskinn May 22, 2024
1d8f043
Fix tox flake8-noqa invocation
bskinn May 22, 2024
1996947
Fix Azure README test job name
bskinn May 22, 2024
385e484
Remove duplicate Azure Pipelines trigger
bskinn May 22, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .github/workflows/ci_tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand Down
32 changes: 30 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
14 changes: 7 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).


Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.:

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion LICENSE.txt
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
@@ -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

Expand Down
211 changes: 211 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading