diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2216901..23d60c5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -43,10 +43,6 @@ repos: - repo: https://github.com/ComPWA/repo-maintenance rev: 0.0.192 hooks: - - id: check-dev-files - args: - - --repo-name=sphinxcontrib-hep-pdgref - - --repo-title=sphinxcontrib.hep.pdgref - id: format-setup-cfg - repo: https://github.com/psf/black @@ -75,11 +71,6 @@ repos: .*\.py )$ - - repo: https://github.com/igorshubovych/markdownlint-cli - rev: v0.35.0 - hooks: - - id: markdownlint - - repo: local hooks: - id: mypy diff --git a/README.md b/README.md index 739f959..bf89351 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,3 @@ # PDG role for Sphinx -[![PyPI package](https://badge.fury.io/py/sphinxcontrib-hep-pdgref.svg)](https://pypi.org/project/sphinxcontrib-hep-pdgref) -[![Supported Python versions](https://img.shields.io/pypi/pyversions/sphinxcontrib-hep-pdgref)](https://pypi.org/project/sphinxcontrib-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/sphinxcontrib-hep-pdgref) -[![GitPod](https://img.shields.io/badge/gitpod-open-blue?logo=gitpod)](https://gitpod.io/#https://github.com/ComPWA/sphinxcontrib-hep-pdgref) -[![Test coverage](https://codecov.io/gh/ComPWA/sphinxcontrib-hep-pdgref/branch/main/graph/badge.svg?token=SS8ZB8J11N)](https://codecov.io/gh/ComPWA/sphinxcontrib-hep-pdgref) -[![Codacy Badge](https://app.codacy.com/project/badge/Grade/dbe042deb2914f6098eb98586d3983fe)](https://www.codacy.com/gh/ComPWA/sphinxcontrib-hep-pdgref) -[![CI status](https://github.com/ComPWA/sphinxcontrib-hep-pdgref/workflows/CI-tests/badge.svg)](https://github.com/ComPWA/sphinxcontrib-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/sphinxcontrib-hep-pdgref/main.svg)](https://results.pre-commit.ci/latest/github/ComPWA/sphinxcontrib-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 sphinxcontrib-hep-pdgref -``` - -Next, in your -[Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html) -(`conf.py`), add `"sphinxcontrib.hep.pdgref"` to your `extensions`: - -```python -extensions = [ - # ... - "sphinxcontrib.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!_ +_This package has been renamed to **[`sphinx-hep-pdgref`](https://pypi.org/project/sphinx-hep-pdgref)**! Please use that package instead._ diff --git a/pyproject.toml b/pyproject.toml index cf07dec..9c69db9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -96,7 +96,10 @@ 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 = [ diff --git a/src/sphinxcontrib/hep/pdgref/__init__.py b/src/sphinxcontrib/hep/pdgref/__init__.py index 83229b5..c789a6a 100644 --- a/src/sphinxcontrib/hep/pdgref/__init__.py +++ b/src/sphinxcontrib/hep/pdgref/__init__.py @@ -1,11 +1,22 @@ """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))