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.
