sphinx-vtk-xref 0.2.1__tar.gz

sphinx_vtk_xref-0.2.1/.github/workflows/test-and-release.yml

@@ -0,0 +1,107 @@
+name: CI
+
+# zizmor ignore note: the release job only consumes artifacts built by the
+# `test` job in this same run, never a cache populated by an earlier/forked
+# run, so opting setup-python into pip caching here is not exploitable.
+on: # zizmor: ignore[cache-poisoning]
+  pull_request:
+  push:
+    tags:
+    - '*'
+    branches:
+    - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.13'
+        cache: pip
+    - name: Run pre-commit
+      run: |
+        pip install --upgrade pip pre-commit
+        pre-commit run --all-files --show-diff-on-failure
+      env:
+        # no-commit-to-branch only makes sense as a local git hook, so skip in CI
+        SKIP: no-commit-to-branch
+
+  test:
+    permissions:
+      contents: read
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install . --group dev
+    - name: Run tests
+      run: pytest -v
+    # Pure-Python package: every matrix leg would build an identical wheel, so
+    # only build/upload once (on the newest Python) to avoid duplicate
+    # dist-artifacts uploads colliding.
+    - name: Build wheel and sdist
+      if: matrix.python-version == '3.14'
+      run: |
+        pip install build
+        python -m build
+    - name: Upload build artifacts
+      if: matrix.python-version == '3.14'
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist-artifacts
+        path: dist/
+
+  release:
+    name: Release
+    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
+    needs: [lint, test]
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/sphinx-vtk-xref
+    permissions:
+      id-token: write  # this permission is mandatory for trusted publishing
+      contents: write  # required to create a release
+    steps:
+    - uses: actions/download-artifact@v4
+    - name: Flatten directory structure
+      run: |
+        mkdir -p dist/
+        find . -name '*.whl' -exec mv {} dist/ \;
+        find . -name '*.tar.gz' -exec mv {} dist/ \;
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc
+      with:
+        verbose: true
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@72f2c25fcb47643c292f7107632f7a47c1df5cd8
+      with:
+        generate_release_notes: true
+        files: |
+          ./**/*.whl

sphinx_vtk_xref-0.2.1/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.idea/
+sphinx_vtk_xref.egg-info/
+__pycache__/
+#*.
+tests/tinypages/_build
+.coverage
+.coverage.*
+dist

sphinx_vtk_xref-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+# Integration with GitHub Actions
+# See https://pre-commit.ci/
+ci:
+  autoupdate_commit_msg: 'chore: update pre-commit hooks'
+  autofix_prs: true
+  autoupdate_schedule: quarterly
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: check-merge-conflict
+  - id: debug-statements
+  - id: no-commit-to-branch
+    args: [--branch, main]
+
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.33.2
+  hooks:
+  - id: check-github-workflows
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.12.8
+  hooks:
+  - id: ruff-check
+    args: [--fix, --show-fixes]
+    exclude: tests/core/typing
+  - id: ruff-format
+    exclude: tests/core/typing
+
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: v1.11.0
+  hooks:
+  - id: zizmor
+
+- repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+  rev: v2.15.0
+  hooks:
+  - id: pretty-format-toml
+    args: [--autofix]
+  - id: pretty-format-yaml
+    args: [--autofix, --indent, '2']

sphinx_vtk_xref-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PyVista
+
+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 the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sphinx_vtk_xref-0.2.1/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: sphinx-vtk-xref
+Version: 0.2.1
+Summary: Sphinx extension for linking to VTK class documentation.
+Author-email: PyVista Developers <info@pyvista.org>
+License: MIT
+Project-URL: Homepage, https://github.com/pyvista/sphinx-vtk-xref
+Classifier: Framework :: Sphinx :: Extension
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: sphinx>=8.1
+Requires-Dist: beautifulsoup4
+Requires-Dist: requests
+Dynamic: license-file
+
+Sphinx VTK XRef
+===============
+
+``sphinx-vtk-xref`` is a Sphinx extension for linking directly to
+`VTK's documentation <https://vtk.org/doc/nightly/html/index.html>`_
+using the ``:vtk:`` reference role.
+
+Installation
+------------
+
+#.  Add ``sphinx-vtk-xref`` as a project dependency or install it with:
+
+    .. code-block:: bash
+
+        pip install sphinx-vtk-xref
+
+#.  Add ``sphinx_vtk_xref`` as an extension in your ``conf.py`` file used by
+    Sphinx. The exact setup depends on whether your documentation is written
+    in reStructuredText or Markdown.
+
+reStructuredText
+~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    extensions = [
+        ...,
+        'sphinx_vtk_xref',
+    ]
+
+Markdown (MyST)
+~~~~~~~~~~~~~~~
+
+Markdown support requires `MyST-Parser <https://myst-parser.readthedocs.io>`_,
+which dispatches Sphinx roles like ``:vtk:`` using its own ``{vtk}`` syntax.
+
+.. code-block:: bash
+
+    pip install myst-parser
+
+.. code-block:: python
+
+    extensions = [
+        ...,
+        'sphinx_vtk_xref',
+        'myst_parser',
+    ]
+    source_suffix = {
+        '.md': 'markdown',
+    }
+
+Usage
+-----
+
+- Add links to VTK class documentation with the ``:vtk:`` role. For
+  example, write ``:vtk:`vtkImageData``` in docstrings to link directly
+  to the ``vtkImageData`` documentation. This will render as
+  `vtkImageData <https://vtk.org/doc/nightly/html/classvtkImageData.html>`_.
+
+  If using MyST, use ``{vtk}`vtkImageData``` instead.
+
+- Link directly to class members such as methods or enums. For example,
+  write ``:vtk:`vtkImageData.GetSpacing``` to link directly to the
+  ``GetSpacing`` method. This will render as
+  `vtkImageData.GetSpacing <https://vtk.org/doc/nightly/html/classvtkImageData.html#ae6ebee83577b2d58c393a0df2f15b67d>`_.
+
+  If using MyST, use ``{vtk}`vtkImageData.GetSpacing``` instead.
+
+- Use ``~`` to shorten the title for the link and only show the class member
+  after the period. For example, ``:vtk:`~vtkImageData.GetSpacing```
+  will render as
+  `GetSpacing <https://vtk.org/doc/nightly/html/classvtkImageData.html#ae6ebee83577b2d58c393a0df2f15b67d>`_.
+
+  If using MyST, use ``{vtk}`~vtkImageData.GetSpacing``` instead.
+
+- Provide a custom title for the reference. For example,
+  ``:vtk:`Get Image Spacing <vtkImageData.GetSpacing>```
+  will render as
+  `Get Image Spacing <https://vtk.org/doc/nightly/html/classvtkImageData.html#ae6ebee83577b2d58c393a0df2f15b67d>`_
+
+  If using MyST, use ``{vtk}`Get Image Spacing <vtkImageData.GetSpacing>```
+  instead.
+
+Configuration
+-------------
+
+The following options can be set in ``conf.py``:
+
+``sphinx_vtk_xref_nitpicky``
+  Bool, default ``True``. Set to ``False`` to disable ``:vtk:`` link
+  checking. This is independent of Sphinx's own ``nitpicky`` option, so
+  you can turn off ``:vtk:`` link validation without affecting how the rest
+  of your project handles missing references. When disabled, the ``:vtk:``
+  role skips the HTTP request used to validate class and member references
+  (and to resolve member anchors) and instead links directly to the
+  (unvalidated) class documentation page.
+
+  .. code-block:: python
+
+      sphinx_vtk_xref_nitpicky = False
+
+``sphinx_vtk_xref_ignored_status_codes``
+  Collection of HTTP status codes, default ``{429, 500, 502, 503, 504}``.
+  These codes typically indicate a transient server-side issue (rate
+  limiting or upstream unavailability) rather than a genuinely-invalid
+  class reference, so they are logged as info messages and do not fail the
+  build, even with Sphinx's ``-W`` flag. The role falls back to the
+  (unvalidated) class URL in this case.
+
+  .. code-block:: python
+
+      sphinx_vtk_xref_ignored_status_codes = {404}
+
+Notes
+-----
+
+- The URLs linking to the VTK documentation are checked to ensure they are valid
+  references. A warning is emitted if the reference is invalid, but the role
+  will still try to point to a valid URL where possible. Combine this with
+  Sphinx's own ``-W`` flag to fail the build on invalid links.
+
+- The role does not currently support linking to nested members. For example,
+  linking to an enum member with ``:vtk:`vtkCommand.EventIds``` works,
+  but linking to a specific enum value with ``:vtk:`vtkCommand.EventIds.PickEvent```
+  does not.

sphinx_vtk_xref-0.2.1/README.rst

@@ -0,0 +1,125 @@
+Sphinx VTK XRef
+===============
+
+``sphinx-vtk-xref`` is a Sphinx extension for linking directly to
+`VTK's documentation <https://vtk.org/doc/nightly/html/index.html>`_
+using the ``:vtk:`` reference role.
+
+Installation
+------------
+
+#.  Add ``sphinx-vtk-xref`` as a project dependency or install it with:
+
+    .. code-block:: bash
+
+        pip install sphinx-vtk-xref
+
+#.  Add ``sphinx_vtk_xref`` as an extension in your ``conf.py`` file used by
+    Sphinx. The exact setup depends on whether your documentation is written
+    in reStructuredText or Markdown.
+
+reStructuredText
+~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    extensions = [
+        ...,
+        'sphinx_vtk_xref',
+    ]
+
+Markdown (MyST)
+~~~~~~~~~~~~~~~
+
+Markdown support requires `MyST-Parser <https://myst-parser.readthedocs.io>`_,
+which dispatches Sphinx roles like ``:vtk:`` using its own ``{vtk}`` syntax.
+
+.. code-block:: bash
+
+    pip install myst-parser
+
+.. code-block:: python
+
+    extensions = [
+        ...,
+        'sphinx_vtk_xref',
+        'myst_parser',
+    ]
+    source_suffix = {
+        '.md': 'markdown',
+    }
+
+Usage
+-----
+
+- Add links to VTK class documentation with the ``:vtk:`` role. For
+  example, write ``:vtk:`vtkImageData``` in docstrings to link directly
+  to the ``vtkImageData`` documentation. This will render as
+  `vtkImageData <https://vtk.org/doc/nightly/html/classvtkImageData.html>`_.
+
+  If using MyST, use ``{vtk}`vtkImageData``` instead.
+
+- Link directly to class members such as methods or enums. For example,
+  write ``:vtk:`vtkImageData.GetSpacing``` to link directly to the
+  ``GetSpacing`` method. This will render as
+  `vtkImageData.GetSpacing <https://vtk.org/doc/nightly/html/classvtkImageData.html#ae6ebee83577b2d58c393a0df2f15b67d>`_.
+
+  If using MyST, use ``{vtk}`vtkImageData.GetSpacing``` instead.
+
+- Use ``~`` to shorten the title for the link and only show the class member
+  after the period. For example, ``:vtk:`~vtkImageData.GetSpacing```
+  will render as
+  `GetSpacing <https://vtk.org/doc/nightly/html/classvtkImageData.html#ae6ebee83577b2d58c393a0df2f15b67d>`_.
+
+  If using MyST, use ``{vtk}`~vtkImageData.GetSpacing``` instead.
+
+- Provide a custom title for the reference. For example,
+  ``:vtk:`Get Image Spacing <vtkImageData.GetSpacing>```
+  will render as
+  `Get Image Spacing <https://vtk.org/doc/nightly/html/classvtkImageData.html#ae6ebee83577b2d58c393a0df2f15b67d>`_
+
+  If using MyST, use ``{vtk}`Get Image Spacing <vtkImageData.GetSpacing>```
+  instead.
+
+Configuration
+-------------
+
+The following options can be set in ``conf.py``:
+
+``sphinx_vtk_xref_nitpicky``
+  Bool, default ``True``. Set to ``False`` to disable ``:vtk:`` link
+  checking. This is independent of Sphinx's own ``nitpicky`` option, so
+  you can turn off ``:vtk:`` link validation without affecting how the rest
+  of your project handles missing references. When disabled, the ``:vtk:``
+  role skips the HTTP request used to validate class and member references
+  (and to resolve member anchors) and instead links directly to the
+  (unvalidated) class documentation page.
+
+  .. code-block:: python
+
+      sphinx_vtk_xref_nitpicky = False
+
+``sphinx_vtk_xref_ignored_status_codes``
+  Collection of HTTP status codes, default ``{429, 500, 502, 503, 504}``.
+  These codes typically indicate a transient server-side issue (rate
+  limiting or upstream unavailability) rather than a genuinely-invalid
+  class reference, so they are logged as info messages and do not fail the
+  build, even with Sphinx's ``-W`` flag. The role falls back to the
+  (unvalidated) class URL in this case.
+
+  .. code-block:: python
+
+      sphinx_vtk_xref_ignored_status_codes = {404}
+
+Notes
+-----
+
+- The URLs linking to the VTK documentation are checked to ensure they are valid
+  references. A warning is emitted if the reference is invalid, but the role
+  will still try to point to a valid URL where possible. Combine this with
+  Sphinx's own ``-W`` flag to fail the build on invalid links.
+
+- The role does not currently support linking to nested members. For example,
+  linking to an enum member with ``:vtk:`vtkCommand.EventIds``` works,
+  but linking to a specific enum value with ``:vtk:`vtkCommand.EventIds.PickEvent```
+  does not.

sphinx_vtk_xref-0.2.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+build-backend = 'setuptools.build_meta'
+requires = ['setuptools>=64', 'setuptools_scm>=8']
+
+[dependency-groups]
+dev = ['pytest', 'pytest-cov', 'pre-commit', 'myst-parser']
+
+[project]
+authors = [{name = 'PyVista Developers', email = 'info@pyvista.org'}]
+classifiers = [
+  "Framework :: Sphinx :: Extension",
+  "License :: OSI Approved :: MIT License"
+]
+dependencies = [
+  'sphinx>=8.1',
+  'beautifulsoup4',
+  'requests'
+]
+description = 'Sphinx extension for linking to VTK class documentation.'
+dynamic = ['version']
+license = {text = 'MIT'}
+name = 'sphinx-vtk-xref'
+readme = 'README.rst'
+requires-python = '>=3.10'
+
+[project.urls]
+Homepage = 'https://github.com/pyvista/sphinx-vtk-xref'
+
+[tool.coverage.run]
+parallel = true
+# The test suite spawns sphinx-build as a subprocess via ``sys.executable``;
+# parallel mode + COVERAGE_PROCESS_START (set in tests/conftest.py) let the
+# ``:vtk:`` role code be measured from inside those subprocesses.
+source = ['sphinx_vtk_xref']
+
+[tool.pytest.ini_options]
+addopts = "--cov=sphinx_vtk_xref --cov-fail-under=85"
+testpaths = 'tests'
+
+[tool.ruff]
+line-length = 100
+
+[tool.setuptools]
+packages = ['sphinx_vtk_xref']
+
+[tool.setuptools_scm]

sphinx_vtk_xref-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+