| 1 |
"""Supporting functions for documentation build.""" |
| 2 |
|
| 3 |
from __future__ import annotations |
| 4 |
|
| 5 |
import inspect |
| 6 |
import os |
| 7 |
import os.path as op |
| 8 |
import sys |
| 9 |
|
| 10 |
|
| 11 |
def linkcode_resolve(domain: str, info: dict[str, str], edit: bool = False) -> str | None: # noqa: FBT001, FBT002 |
| 12 |
"""Determine the URL corresponding to a Python object. |
| 13 |
|
| 14 |
Parameters |
| 15 |
---------- |
| 16 |
domain : str |
| 17 |
Only useful when 'py'. |
| 18 |
|
| 19 |
info : dict |
| 20 |
With keys "module" and "fullname". |
| 21 |
|
| 22 |
edit : bool, default=False |
| 23 |
Jump right to the edit page. |
| 24 |
|
| 25 |
Returns |
| 26 |
------- |
| 27 |
str |
| 28 |
The code URL. Empty string if there is no valid link. |
| 29 |
|
| 30 |
Notes |
| 31 |
----- |
| 32 |
This function is used by the `sphinx.ext.linkcode` extension to create the "[Source]" |
| 33 |
button whose link is edited in this function. |
| 34 |
|
| 35 |
This has been adapted to deal with our "verbose" decorator. |
| 36 |
|
| 37 |
Adapted from mne (mne/utils/docs.py), which was adapted from SciPy (doc/source/conf.py). |
| 38 |
|
| 39 |
""" |
| 40 |
import pyvista as pv # noqa: PLC0415 |
| 41 |
|
| 42 |
if domain != 'py': |
| 43 |
return None |
| 44 |
|
| 45 |
modname = info['module'] |
| 46 |
fullname = info['fullname'] |
| 47 |
|
| 48 |
# Little clean up to avoid pyvista.pyvista |
| 49 |
if fullname.startswith(modname): |
| 50 |
fullname = fullname[len(modname) + 1 :] |
| 51 |
|
| 52 |
submod = sys.modules.get(modname) |
| 53 |
if submod is None: |
| 54 |
return None |
| 55 |
|
| 56 |
obj = submod |
| 57 |
for part in fullname.split('.'): |
| 58 |
try: |
| 59 |
obj = getattr(obj, part) |
| 60 |
except Exception: # noqa: BLE001 |
| 61 |
return None |
| 62 |
|
| 63 |
# deal with our decorators properly |
| 64 |
while hasattr(obj, 'fget'): |
| 65 |
obj = obj.fget |
| 66 |
|
| 67 |
# deal with wrapped object |
| 68 |
while hasattr(obj, '__wrapped__'): |
| 69 |
obj = obj.__wrapped__ |
| 70 |
try: |
| 71 |
fn = inspect.getsourcefile(obj) |
| 72 |
except Exception: # noqa: BLE001 # pragma: no cover |
| 73 |
fn = None |
| 74 |
|
| 75 |
if not fn: # pragma: no cover |
| 76 |
try: |
| 77 |
fn = inspect.getsourcefile(sys.modules[obj.__module__]) |
| 78 |
except Exception: # noqa: BLE001 |
| 79 |
return None |
| 80 |
return None |
| 81 |
|
| 82 |
fn = op.relpath(fn, start=op.dirname(pv.__file__)) # noqa: PTH120 |
| 83 |
fn = '/'.join(op.normpath(fn).split(os.sep)) # in case on Windows # noqa: PTH206 |
| 84 |
|
| 85 |
try: |
| 86 |
source, lineno = inspect.getsourcelines(obj) |
| 87 |
except Exception: # noqa: BLE001 # pragma: no cover |
| 88 |
lineno = None |
| 89 |
|
| 90 |
linespec = f'#L{lineno}-L{lineno + len(source) - 1}' if lineno and not edit else '' |
| 91 |
|
| 92 |
if 'dev' in pv.__version__: |
| 93 |
kind = 'main' |
| 94 |
else: # pragma: no cover |
| 95 |
kind = f'release/{".".join(pv.__version__.split(".")[:2])}' |
| 96 |
|
| 97 |
blob_or_edit = 'edit' if edit else 'blob' |
| 98 |
|
| 99 |
return f'http://github.com/pyvista/pyvista/{blob_or_edit}/{kind}/pyvista/{fn}{linespec}' |
| 100 |
|
| 101 |
|
| 102 |
def pv_html_page_context( # noqa: PLR0917 |
| 103 |
app, # noqa: ARG001 |
| 104 |
pagename: str, |
| 105 |
templatename: str, # noqa: ARG001 |
| 106 |
context, |
| 107 |
doctree, # noqa: ARG001 |
| 108 |
) -> None: # pragma: no cover |
| 109 |
"""Add a function for returning an "edit this page" link pointing to `main`. |
| 110 |
|
| 111 |
This is specific to PyVista to ensure that the "edit this page" link always |
| 112 |
goes to the right page, specifically for: |
| 113 |
|
| 114 |
- Gallery examples |
| 115 |
- Autosummary examples (using _autosummary) |
| 116 |
|
| 117 |
""" |
| 118 |
|
| 119 |
def fix_edit_link_button(link: str) -> str | None: |
| 120 |
"""Transform "edit on github" links to the correct url. |
| 121 |
|
| 122 |
This is specific to PyVista to ensure that the "edit this page" link |
| 123 |
always goes to the right page, specifically for: |
| 124 |
|
| 125 |
- Gallery examples |
| 126 |
- Autosummary examples (using _autosummary) |
| 127 |
|
| 128 |
Parameters |
| 129 |
---------- |
| 130 |
link : str |
| 131 |
The link to the github edit interface. |
| 132 |
|
| 133 |
Returns |
| 134 |
------- |
| 135 |
str |
| 136 |
The link to the tip of the main branch for the same file. |
| 137 |
|
| 138 |
""" |
| 139 |
if pagename.startswith('examples') and 'index' not in pagename: |
| 140 |
# This is a gallery example. |
| 141 |
|
| 142 |
# We can get away with directly using the pagename since "examples" |
| 143 |
# in the pagename is the same as the "examples" directory in the |
| 144 |
# repo |
| 145 |
return f'http://github.com/pyvista/pyvista/edit/main/{pagename}.py' |
| 146 |
elif '_autosummary' in pagename: |
| 147 |
# This is an API example |
| 148 |
fullname = pagename.split('_autosummary')[1][1:] |
| 149 |
return linkcode_resolve('py', {'module': 'pyvista', 'fullname': fullname}, edit=True) |
| 150 |
else: |
| 151 |
return link |
| 152 |
|
| 153 |
context['fix_edit_link_button'] = fix_edit_link_button |