Debian Codegraph @

pyvista/core/utilities/docs.py

raw
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