Skip to content

Commit 8d9dac3

Browse files
redeboerredeboer
authored
BREAK: rename package to sphinx-hep-pdgref (#31)
* FIX: import `sphinx.testing.path` for lower Sphinx versions * MAINT: remove `pkg_resources` deprecation warning
1 parent fef60ef commit 8d9dac3

File tree

22 files changed

+122
-55
lines changed

22 files changed

+122
-55
lines changed

‎.cspell.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,6 @@
7272
"rtfd",
7373
"sdist",
7474
"setuptools",
75-
"sphinxcontrib",
7675
"testroot",
7776
"unittests",
7877
"venv"

‎.github/release-drafter.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name-template: sphinxcontrib.hep.pdgref $NEXT_PATCH_VERSION
1+
name-template: sphinx-hep-pdgref $NEXT_PATCH_VERSION
22
tag-template: $NEXT_PATCH_VERSION
33

44
references:
@@ -34,4 +34,4 @@ sort-direction: ascending
3434
template: |
3535
$CHANGES
3636
37-
_The full changelog as commits can be found [here](https://github.com/ComPWA/sphinxcontrib-hep-pdgref/compare/$PREVIOUS_TAG...$NEXT_PATCH_VERSION)._
37+
_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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ jobs:
2929
pytest:
3030
uses: ComPWA/actions/.github/workflows/pytest.yml@v1
3131
with:
32-
coverage-target: sphinxcontrib
32+
coverage-target: sphinx_hep_pdgref
3333
macos-python-version: "3.9"
3434
specific-pip-packages: ${{ inputs.specific-pip-packages }}
3535
style:

‎.pre-commit-config.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ repos:
4343
- repo: https://github.com/ComPWA/repo-maintenance
4444
rev: 0.0.192
4545
hooks:
46+
- id: check-dev-files
47+
args:
48+
- --repo-name=sphinx-hep-pdgref
49+
- --repo-title=sphinx-hep-pdgref
4650
- id: format-setup-cfg
4751

4852
- repo: https://github.com/psf/black

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# How to contribute?
22

3-
[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinxcontrib-hep-pdgref)
4-
[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinxcontrib-hep-pdgref)
3+
[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-hep-pdgref)
4+
[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinx-hep-pdgref)
55

66
This package is part of the [ComPWA Organization](https://github.com/ComPWA). For more
77
information about how to contribute to the packages, go to

‎README.md‎

Lines changed: 75 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,77 @@
11
# PDG role for Sphinx
22

3-
_This package has been renamed to **[`sphinx-hep-pdgref`](https://pypi.org/project/sphinx-hep-pdgref)**! Please use that package instead._
3+
[![PyPI package](https://badge.fury.io/py/sphinx-hep-pdgref.svg)](https://pypi.org/project/sphinx-hep-pdgref)
4+
[![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinx-hep-pdgref)](https://pypi.org/project/sphinx-hep-pdgref)
5+
[![BSD 3-Clause license](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
6+
[![Open in Visual Studio Code](https://img.shields.io/badge/vscode-open-blue?logo=visualstudiocode)](https://open.vscode.dev/ComPWA/sphinx-hep-pdgref)
7+
[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinx-hep-pdgref)
8+
[![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)
9+
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/dbe042deb2914f6098eb98586d3983fe)](https://www.codacy.com/gh/ComPWA/sphinx-hep-pdgref)
10+
[![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)
11+
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy.readthedocs.io)
12+
[![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)
13+
[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/master/packages/cspell)
14+
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
15+
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
16+
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
17+
18+
This package is a
19+
[Sphinx extension](https://www.sphinx-doc.org/en/master/usage/extensions/index.html)
20+
that makes it easy to refer to PDF files of reviews and particle listings in the PDG.
21+
22+
## Installation
23+
24+
Just install through [PyPI](https://pypi.org) with `pip`:
25+
26+
```bash
27+
pip install sphinx-hep-pdgref
28+
```
29+
30+
Next, in your
31+
[Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)
32+
(`conf.py`), add `"sphinx_hep_pdgref"` to your `extensions`:
33+
34+
```python
35+
extensions = [
36+
# ...
37+
"sphinx_hep_pdgref",
38+
# ...
39+
]
40+
```
41+
42+
## Usage
43+
44+
There are two roles, one for the
45+
[particle listings](https://pdg.lbl.gov/2020/listings/contents_listings.html) and one
46+
for the [review](https://pdg.lbl.gov/2020/reviews/contents_sports.html). These roles can
47+
be used as follows:
48+
49+
```restructuredtext
50+
:pdg-listing:`K-zero`
51+
52+
:pdg-review:`Kinematics`
53+
54+
:pdg-review:`2014; Resonances`
55+
56+
:pdg-review:`Resonances; 2018; pp. 2-4, 7`
57+
58+
:pdg-review:`QCD; p5`
59+
60+
:pdg-review:`PDG2015; Quark Model; p.2`
61+
```
62+
63+
which will render in the HTML pages as:
64+
65+
> [PDG2020](https://pdg.lbl.gov/2020/listings/rpp2020-list-K-zero.pdf)
66+
>
67+
> [PDG2020, §Kinematics](https://pdg.lbl.gov/2020/reviews/rpp2020-rev-kinematics.pdf)
68+
>
69+
> [PDG2014, §Resonances](https://pdg.lbl.gov/2014/reviews/rpp2014-rev-resonances.pdf)
70+
>
71+
> [PDG2018, §Resonances, pp.2-4,7](https://pdg.lbl.gov/2018/reviews/rpp2018-rev-resonances.pdf#page=2)
72+
>
73+
> [PDG2020, §QCD, p.5](https://pdg.lbl.gov/2020/reviews/rpp2020-rev-qcd.pdf#page=5)
74+
>
75+
> [PDG2015, §Quark Model, p.2](https://pdg.lbl.gov/2015/reviews/rpp2015-rev-qcd.pdf#page=2)
76+
77+
_Note that the resulting links lead to the correct page as well!_

‎environment.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
name: sphinxcontrib-hep-pdgref
1+
name: sphinx-hep-pdgref
22
channels:
33
- defaults
44
dependencies:

‎pyproject.toml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ reportUnknownArgumentType = false
8181
reportUnknownMemberType = false
8282
reportUnknownParameterType = false
8383
reportUnknownVariableType = false
84+
reportUntypedFunctionDecorator = false
8485
reportUnusedClass = true
8586
reportUnusedFunction = true
8687
reportUnusedImport = true
@@ -96,10 +97,7 @@ addopts = """
9697
filterwarnings = [
9798
"error",
9899
"ignore:'imghdr' is deprecated and slated for removal in Python 3.13:DeprecationWarning",
99-
"ignore:.*:PendingDeprecationWarning",
100-
"ignore:.*pkg_resources.*:DeprecationWarning",
101100
"ignore:The distutils package is deprecated.*:DeprecationWarning",
102-
"ignore:The sphinxcontrib.hep.pdgref package is deprecated.*:DeprecationWarning",
103101
]
104102
markers = ["slow: marks tests as slow (deselect with '-m \"not slow\"')"]
105103
testpaths = [

‎setup.cfg‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
[metadata]
2-
name = sphinxcontrib-hep-pdgref
2+
name = sphinx-hep-pdgref
33
author = Common Partial Wave Analysis
44
author_email = compwa-admin@ep1.rub.de
55
maintainer_email = compwa-admin@ep1.rub.de
66
description = Sphinx role for linking to PDG reviews and listing
77
long_description = file: README.md
88
long_description_content_type = text/markdown
99
project_urls =
10-
Tracker = https://github.com/ComPWA/sphinxcontrib-hep-pdgref/issues
11-
Changelog = https://github.com/ComPWA/sphinxcontrib-hep-pdgref/releases
12-
Documentation = https://github.com/ComPWA/sphinxcontrib-hep-pdgref/blob/main/README.md
13-
Source = https://github.com/ComPWA/sphinxcontrib-hep-pdgref
10+
Tracker = https://github.com/ComPWA/sphinx-hep-pdgref/issues
11+
Changelog = https://github.com/ComPWA/sphinx-hep-pdgref/releases
12+
Documentation = https://github.com/ComPWA/sphinx-hep-pdgref/blob/main/README.md
13+
Source = https://github.com/ComPWA/sphinx-hep-pdgref
1414
license = BSD 3-Clause License
1515
license_files = LICENSE
1616
keywords =
@@ -44,13 +44,13 @@ install_requires =
4444
docutils
4545
Sphinx
4646
include_package_data = True
47-
namespace_packages = sphinxcontrib
4847
package_dir =
4948
=src
50-
packages = find_namespace:
49+
packages = find:
5150

5251
[options.extras_require]
5352
test =
53+
importlib-metadata; python_version <"3.8.0"
5454
pyquery # for checking HTML output
5555
pytest
5656
pytest-cov
@@ -75,8 +75,6 @@ dev =
7575
tox >=1.9 # for skip_install, use_develop
7676

7777
[options.packages.find]
78-
include =
79-
sphinxcontrib.hep.*
8078
where = src
8179

8280
[options.package_data]

‎src/sphinxcontrib/hep/pdgref/__init__.py‎ renamed to ‎src/sphinx_hep_pdgref/__init__.py‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,11 @@
11
"""Link to PDG reviews and listings in Sphinx documentation."""
22

33
from typing import Any, Dict
4-
from warnings import warn
54

65
from sphinx.application import Sphinx
76

87
from .role import URLPattern, pdgref
98

10-
warn(
11-
(
12-
"The sphinxcontrib.hep.pdgref package is deprecated. Please install the"
13-
" [sphinx-hep-pdgref](https://pypi.org/project/sphinx-hep-pdgref) package and"
14-
" import `sphinx_hep_pdg` instead."
15-
),
16-
category=DeprecationWarning,
17-
stacklevel=2,
18-
)
19-
209

2110
def setup(app: Sphinx) -> Dict[str, Any]:
2211
app.add_role("pdg-listing", role=pdgref(pattern=URLPattern.LISTING))

0 commit comments

Comments
 (0)