Metadata-Version: 2.4
Name: vtk-xref
Version: 0.1.2
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/vtk-xref
Classifier: Framework :: Sphinx :: Extension
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: sphinx>=4.0
Requires-Dist: beautifulsoup4
Requires-Dist: requests
Dynamic: license-file

VTK XRef
========

``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 ``vtk-xref`` as a project dependency or install it with:

    .. code-block:: bash

        pip install vtk-xref


#.  Add ``vtk_xref`` as an extension in your ``conf.py`` file
    used by Sphinx:

.. code-block:: python

    extensions = [
        ...,
        'vtk_xref',
    ]

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>`_.

- 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>`_.

- 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>`_.

- 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>`_

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. It is recommended to
  set ``nitpicky=True`` in ``conf.py`` when using this extension to ensure all
  links are valid and correct.

- 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.
