diff --git a/.cspell.json b/.cspell.json index 5ca40a3..d61eb4c 100644 --- a/.cspell.json +++ b/.cspell.json @@ -72,7 +72,6 @@ "rtfd", "sdist", "setuptools", - "sphinxcontrib", "testroot", "unittests", "venv" diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 032b3f8..e011474 100644 --- a/.github/release-drafter.yml +++ b/.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)._ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b0d07fc..c89d68e 100644 --- a/.github/workflows/ci.yml +++ b/.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: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 23d60c5..6fa8340 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e587f1..00fc254 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index bf89351..39e61f6 100644 --- a/README.md +++ b/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!_ diff --git a/environment.yml b/environment.yml index 8dd2d97..7abb94c 100644 --- a/environment.yml +++ b/environment.yml @@ -1,4 +1,4 @@ -name: sphinxcontrib-hep-pdgref +name: sphinx-hep-pdgref channels: - defaults dependencies: diff --git a/pyproject.toml b/pyproject.toml index 9c69db9..e157398 100644 --- a/pyproject.toml +++ b/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 = [ diff --git a/setup.cfg b/setup.cfg index f587c78..c5172c4 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [metadata] -name = sphinxcontrib-hep-pdgref +name = sphinx-hep-pdgref author = Common Partial Wave Analysis author_email = compwa-admin@ep1.rub.de maintainer_email = compwa-admin@ep1.rub.de @@ -7,10 +7,10 @@ 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] diff --git a/src/sphinxcontrib/hep/pdgref/__init__.py b/src/sphinx_hep_pdgref/__init__.py similarity index 59% rename from src/sphinxcontrib/hep/pdgref/__init__.py rename to src/sphinx_hep_pdgref/__init__.py index c789a6a..83229b5 100644 --- a/src/sphinxcontrib/hep/pdgref/__init__.py +++ b/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)) diff --git a/src/sphinxcontrib/hep/pdgref/entry.py b/src/sphinx_hep_pdgref/entry.py similarity index 97% rename from src/sphinxcontrib/hep/pdgref/entry.py rename to src/sphinx_hep_pdgref/entry.py index 75087da..79b2db3 100644 --- a/src/sphinxcontrib/hep/pdgref/entry.py +++ b/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") diff --git a/src/sphinxcontrib/hep/pdgref/py.typed b/src/sphinx_hep_pdgref/py.typed similarity index 100% rename from src/sphinxcontrib/hep/pdgref/py.typed rename to src/sphinx_hep_pdgref/py.typed diff --git a/src/sphinxcontrib/hep/pdgref/role.py b/src/sphinx_hep_pdgref/role.py similarity index 100% rename from src/sphinxcontrib/hep/pdgref/role.py rename to src/sphinx_hep_pdgref/role.py diff --git a/src/sphinxcontrib/hep/pdgref/url.py b/src/sphinx_hep_pdgref/url.py similarity index 100% rename from src/sphinxcontrib/hep/pdgref/url.py rename to src/sphinx_hep_pdgref/url.py diff --git a/src/sphinxcontrib/__init__.py b/src/sphinxcontrib/__init__.py deleted file mode 100644 index 8fcee1d..0000000 --- a/src/sphinxcontrib/__init__.py +++ /dev/null @@ -1,6 +0,0 @@ -"""Legacy namespace file. - -https://setuptools.readthedocs.io/en/latest/userguide/package_discovery.html -""" - -__import__("pkg_resources").declare_namespace(__name__) diff --git a/src/sphinxcontrib/hep/__init__.py b/src/sphinxcontrib/hep/__init__.py deleted file mode 100644 index 8fcee1d..0000000 --- a/src/sphinxcontrib/hep/__init__.py +++ /dev/null @@ -1,6 +0,0 @@ -"""Legacy namespace file. - -https://setuptools.readthedocs.io/en/latest/userguide/package_discovery.html -""" - -__import__("pkg_resources").declare_namespace(__name__) diff --git a/tests/conftest.py b/tests/conftest.py index 62c0662..c504c48 100644 --- a/tests/conftest.py +++ b/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" diff --git a/tests/roots/test-dummy/conf.py b/tests/roots/test-dummy/conf.py index 6e87ae2..058a379 100644 --- a/tests/roots/test-dummy/conf.py +++ b/tests/roots/test-dummy/conf.py @@ -1,2 +1,2 @@ -extensions = ["sphinxcontrib.hep.pdgref"] +extensions = ["sphinx_hep_pdgref"] exclude_patterns = ["_build"] diff --git a/tests/test_entry.py b/tests/test_entry.py index c5c4afc..3255e3f 100644 --- a/tests/test_entry.py +++ b/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, diff --git a/tests/test_role.py b/tests/test_role.py index f25786f..eac5f8a 100644 --- a/tests/test_role.py +++ b/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") diff --git a/tests/test_url.py b/tests/test_url.py index 65b1bfa..37c4538 100644 --- a/tests/test_url.py +++ b/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, diff --git a/tox.ini b/tox.ini index fb46840..4aff652 100644 --- a/tox.ini +++ b/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 =