BREAK: rename package to sphinx-hep-pdgref (#31)

* FIX: import `sphinx.testing.path` for lower Sphinx versions
* MAINT: remove `pkg_resources` deprecation warning

.cspell.json

@@ -72,7 +72,6 @@
     "rtfd",
     "sdist",
     "setuptools",
-    "sphinxcontrib",
     "testroot",
     "unittests",
     "venv"

.github/release-drafter.yml

@@ -1,4 +1,4 @@
-name-template: sphinxcontrib.hep.pdgref $NEXT_PATCH_VERSION
+name-template: sphinx-hep-pdgref $NEXT_PATCH_VERSION
 tag-template: $NEXT_PATCH_VERSION
 
 references:
@@ -34,4 +34,4 @@ sort-direction: ascending
 template: |
   $CHANGES
 
-  _The full changelog as commits can be found [here](https://github.com/ComPWA/sphinxcontrib-hep-pdgref/compare/$PREVIOUS_TAG...$NEXT_PATCH_VERSION)._
+  _The full changelog as commits can be found [here](https://github.com/ComPWA/sphinx-hep-pdgref/compare/$PREVIOUS_TAG...$NEXT_PATCH_VERSION)._

.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
   pytest:
     uses: ComPWA/actions/.github/workflows/pytest.yml@v1
     with:
-      coverage-target: sphinxcontrib
+      coverage-target: sphinx_hep_pdgref
       macos-python-version: "3.9"
       specific-pip-packages: ${{ inputs.specific-pip-packages }}
   style:

.pre-commit-config.yaml

@@ -43,6 +43,10 @@ repos:
   - repo: https://github.com/ComPWA/repo-maintenance
     rev: 0.0.192
     hooks:
+      - id: check-dev-files
+        args:
+          - --repo-name=sphinx-hep-pdgref
+          - --repo-title=sphinx-hep-pdgref
       - id: format-setup-cfg
 
   - repo: https://github.com/psf/black

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # How to contribute?
 
-[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinxcontrib-hep-pdgref)
-[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinxcontrib-hep-pdgref)
+[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-hep-pdgref)
+[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinx-hep-pdgref)
 
 This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more
 information about how to contribute to the packages, go to

README.md

@@ -1,3 +1,77 @@
 # PDG role for Sphinx
 
-_This package has been renamed to **[`sphinx-hep-pdgref`](https://pypi.org/project/sphinx-hep-pdgref)**! Please use that package instead._
+[![PyPI package](https://badge.fury.io/py/sphinx-hep-pdgref.svg)](https://pypi.org/project/sphinx-hep-pdgref)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinx-hep-pdgref)](https://pypi.org/project/sphinx-hep-pdgref)
+[![BSD 3-Clause license](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-hep-pdgref)
+[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinx-hep-pdgref)
+[![Test coverage](https://codecov.io/gh/ComPWA/sphinx-hep-pdgref/branch/main/graph/badge.svg?token=SS8ZB8J11N)](https://codecov.io/gh/ComPWA/sphinx-hep-pdgref)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/dbe042deb2914f6098eb98586d3983fe)](https://www.codacy.com/gh/ComPWA/sphinx-hep-pdgref)
+[![CI status](https://github.com/ComPWA/sphinx-hep-pdgref/workflows/CI-tests/badge.svg)](https://github.com/ComPWA/sphinx-hep-pdgref/actions?query=branch%3Amain+workflow%3ACI-tests)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy.readthedocs.io)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/ComPWA/sphinx-hep-pdgref/main.svg)](https://results.pre-commit.ci/latest/github/ComPWA/sphinx-hep-pdgref/main)
+[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+This package is a
+[Sphinx extension](https://www.sphinx-doc.org/en/master/usage/extensions/index.html)
+that makes it easy to refer to PDF files of reviews and particle listings in the PDG.
+
+## Installation
+
+Just install through [PyPI](https://pypi.org) with `pip`:
+
+```bash
+pip install sphinx-hep-pdgref
+```
+
+Next, in your
+[Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)
+(`conf.py`), add `"sphinx_hep_pdgref"` to your `extensions`:
+
+```python
+extensions = [
+    # ...
+    "sphinx_hep_pdgref",
+    # ...
+]
+```
+
+## Usage
+
+There are two roles, one for the
+[particle listings](https://pdg.lbl.gov/2020/listings/contents_listings.html) and one
+for the [review](https://pdg.lbl.gov/2020/reviews/contents_sports.html). These roles can
+be used as follows:
+
+```restructuredtext
+:pdg-listing:`K-zero`
+
+:pdg-review:`Kinematics`
+
+:pdg-review:`2014; Resonances`
+
+:pdg-review:`Resonances; 2018; pp. 2-4, 7`
+
+:pdg-review:`QCD; p5`
+
+:pdg-review:`PDG2015; Quark Model; p.2`
+```
+
+which will render in the HTML pages as:
+
+> [PDG2020](https://pdg.lbl.gov/2020/listings/rpp2020-list-K-zero.pdf)
+>
+> [PDG2020, §Kinematics](https://pdg.lbl.gov/2020/reviews/rpp2020-rev-kinematics.pdf)
+>
+> [PDG2014, §Resonances](https://pdg.lbl.gov/2014/reviews/rpp2014-rev-resonances.pdf)
+>
+> [PDG2018, §Resonances, pp.2-4,7](https://pdg.lbl.gov/2018/reviews/rpp2018-rev-resonances.pdf#page=2)
+>
+> [PDG2020, §QCD, p.5](https://pdg.lbl.gov/2020/reviews/rpp2020-rev-qcd.pdf#page=5)
+>
+> [PDG2015, §Quark Model, p.2](https://pdg.lbl.gov/2015/reviews/rpp2015-rev-qcd.pdf#page=2)
+
+_Note that the resulting links lead to the correct page as well!_

environment.yml

@@ -1,4 +1,4 @@
-name: sphinxcontrib-hep-pdgref
+name: sphinx-hep-pdgref
 channels:
   - defaults
 dependencies:

pyproject.toml

@@ -81,6 +81,7 @@ reportUnknownArgumentType = false
 reportUnknownMemberType = false
 reportUnknownParameterType = false
 reportUnknownVariableType = false
+reportUntypedFunctionDecorator = false
 reportUnusedClass = true
 reportUnusedFunction = true
 reportUnusedImport = true
@@ -96,10 +97,7 @@ addopts = """
 filterwarnings = [
     "error",
     "ignore:'imghdr' is deprecated and slated for removal in Python 3.13:DeprecationWarning",
-    "ignore:.*:PendingDeprecationWarning",
-    "ignore:.*pkg_resources.*:DeprecationWarning",
     "ignore:The distutils package is deprecated.*:DeprecationWarning",
-    "ignore:The sphinxcontrib.hep.pdgref package is deprecated.*:DeprecationWarning",
 ]
 markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]
 testpaths = [

setup.cfg

@@ -1,16 +1,16 @@
 [metadata]
-name = sphinxcontrib-hep-pdgref
+name = sphinx-hep-pdgref
 author = Common Partial Wave Analysis
 author_email = [email protected]
 maintainer_email = [email protected]
 description = Sphinx role for linking to PDG reviews and listing
 long_description = file: README.md
 long_description_content_type = text/markdown
 project_urls =
-    Tracker = https://github.com/ComPWA/sphinxcontrib-hep-pdgref/issues
-    Changelog = https://github.com/ComPWA/sphinxcontrib-hep-pdgref/releases
-    Documentation = https://github.com/ComPWA/sphinxcontrib-hep-pdgref/blob/main/README.md
-    Source = https://github.com/ComPWA/sphinxcontrib-hep-pdgref
+    Tracker = https://github.com/ComPWA/sphinx-hep-pdgref/issues
+    Changelog = https://github.com/ComPWA/sphinx-hep-pdgref/releases
+    Documentation = https://github.com/ComPWA/sphinx-hep-pdgref/blob/main/README.md
+    Source = https://github.com/ComPWA/sphinx-hep-pdgref
 license = BSD 3-Clause License
 license_files = LICENSE
 keywords =
@@ -44,13 +44,13 @@ install_requires =
     docutils
     Sphinx
 include_package_data = True
-namespace_packages = sphinxcontrib
 package_dir =
     =src
-packages = find_namespace:
+packages = find:
 
 [options.extras_require]
 test =
+    importlib-metadata; python_version <"3.8.0"
     pyquery  # for checking HTML output
     pytest
     pytest-cov
@@ -75,8 +75,6 @@ dev =
     tox >=1.9  # for skip_install, use_develop
 
 [options.packages.find]
-include =
-    sphinxcontrib.hep.*
 where = src
 
 [options.package_data]

src/sphinxcontrib/hep/pdgref/__init__.py → src/sphinx_hep_pdgref/__init__.py

@@ -1,22 +1,11 @@
 """Link to PDG reviews and listings in Sphinx documentation."""
 
 from typing import Any, Dict
-from warnings import warn
 
 from sphinx.application import Sphinx
 
 from .role import URLPattern, pdgref
 
-warn(
-    (
-        "The sphinxcontrib.hep.pdgref package is deprecated. Please install the"
-        " [sphinx-hep-pdgref](https://pypi.org/project/sphinx-hep-pdgref) package and"
-        " import `sphinx_hep_pdg` instead."
-    ),
-    category=DeprecationWarning,
-    stacklevel=2,
-)
-
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_role("pdg-listing", role=pdgref(pattern=URLPattern.LISTING))

src/sphinxcontrib/hep/pdgref/entry.py → src/sphinx_hep_pdgref/entry.py

@@ -40,7 +40,7 @@ def __attrs_post_init__(self) -> None:
     def from_str(text: str) -> "PDGEntry":
         """Create an entry from the contents of the :code:`pdg` role.
 
-        >>> from sphinxcontrib.hep.pdgref.entry import PDGEntry
+        >>> from sphinx_hep_pdgref.entry import PDGEntry
         >>> PDGEntry.from_str("Resonances; 2018; p.5")
         PDGEntry(section='Resonances', year=2018, pages='5')
         >>> PDGEntry.from_str("Resonances")

tests/conftest.py

@@ -1,11 +1,28 @@
-# cspell:ignore rootdir
+import sys
+
 import pytest
-from sphinx.testing.path import path
+
+if sys.version_info < (3, 8):
+    from importlib_metadata import version
+else:
+    from importlib.metadata import version
 
 pytest_plugins = "sphinx.testing.fixtures"
 collect_ignore = ["roots"]
 
 
-@pytest.fixture(scope="session")
-def rootdir() -> path:
-    return path(__file__).parent.abspath() / "roots"
+# cspell:ignore rootdir
+sphinx_version = version("Sphinx")
+if sphinx_version < "7.2":
+    from sphinx.testing.path import path
+
+    @pytest.fixture(scope="session")
+    def rootdir() -> path:
+        return path(__file__).parent.abspath() / "roots"
+
+else:
+    from pathlib import Path
+
+    @pytest.fixture(scope="session")
+    def rootdir() -> Path:
+        return Path(__file__).parent.absolute() / "roots"

tests/roots/test-dummy/conf.py

@@ -1,2 +1,2 @@
-extensions = ["sphinxcontrib.hep.pdgref"]
+extensions = ["sphinx_hep_pdgref"]
 exclude_patterns = ["_build"]

tests/test_entry.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from sphinxcontrib.hep.pdgref.entry import (
+from sphinx_hep_pdgref.entry import (
     DEFAULT_YEAR,
     PDGEntry,
     get_first_page,

tests/test_role.py

@@ -1,7 +1,7 @@
 import pyquery as pq  # pyright: ignore[reportMissingTypeStubs]
 import pytest
 
-from sphinxcontrib.hep.pdgref.entry import DEFAULT_YEAR  # type:ignore[import]
+from sphinx_hep_pdgref.entry import DEFAULT_YEAR  # type:ignore[import]
 
 
 @pytest.mark.sphinx("text", testroot="dummy")

tests/test_url.py

@@ -1,7 +1,7 @@
 import pytest
 
-from sphinxcontrib.hep.pdgref.entry import DEFAULT_YEAR, PDGEntry  # type:ignore[import]
-from sphinxcontrib.hep.pdgref.url import (  # type:ignore[import]
+from sphinx_hep_pdgref.entry import DEFAULT_YEAR, PDGEntry  # type:ignore[import]
+from sphinx_hep_pdgref.url import (  # type:ignore[import]
     URLPattern,
     create_link_text,
     create_url,

tox.ini

@@ -18,7 +18,7 @@ commands =
         --cov-fail-under=90 \
         --cov-report=html \
         --cov-report=xml \
-        --cov=sphinxcontrib.hep.pdgref
+        --cov=sphinx_hep_pdgref
 
 [testenv:sty]
 description =