0
# RST Directives
1
2
Custom Sphinx directives for controlling link generation behavior, including example display, code concatenation, prefacing, and selective skipping. These directives provide fine-grained control over how the extension processes code blocks in your documentation.
3
4
## Capabilities
5
6
### Examples Directive
7
8
Display references to code examples for a given object, creating a collapsible table showing where the object appears in documentation code blocks.
9
10
```python { .api }
11
# Directive syntax:
12
# .. autolink-examples:: <object_name>
13
# :collapse:
14
# :type: <reference_type>
15
16
class Examples(Directive):
17
"""
18
Gather and display references in code examples.
19
20
Creates a backreference table showing all code examples that use
21
the specified object, with links to those examples.
22
"""
23
has_content = False
24
required_arguments = 1 # object name
25
optional_arguments = 0
26
option_spec = {
27
"collapse": "flag", # Make table collapsible
28
"type": "unchanged" # Reference type (default: "class")
29
}
30
```
31
32
### Concatenation Directive
33
34
Toggle and control block concatenation in a document, allowing multiple adjacent code blocks to be treated as a single continuous code context.
35
36
```python { .api }
37
# Directive syntax:
38
# .. autolink-concat:: [on|off|section]
39
40
class Concat(Directive):
41
"""
42
Toggle and cut block concatenation in a document.
43
44
Controls whether adjacent code blocks should be concatenated
45
together for analysis, maintaining variable state across blocks.
46
"""
47
has_content = False
48
required_arguments = 0
49
optional_arguments = 1 # mode: "on", "off", or "section"
50
```
51
52
### Preface Directive
53
54
Include preface code in the next code block, allowing you to specify imports or setup code that should be prepended during analysis without displaying it.
55
56
```python { .api }
57
# Directive syntax:
58
# .. autolink-preface:: [level]
59
# content lines...
60
61
class Preface(Directive):
62
"""
63
Include a preface in the next code block.
64
65
Adds setup code (like imports) to code blocks for analysis
66
without displaying the preface code in the output.
67
"""
68
has_content = True
69
required_arguments = 0
70
optional_arguments = 1
71
final_argument_whitespace = True
72
option_spec = {
73
"level": "unchanged" # "next", "file", etc.
74
}
75
```
76
77
### Skip Directive
78
79
Skip auto-linking for the next code block or range of content, providing selective control over which code blocks receive automatic linking.
80
81
```python { .api }
82
# Directive syntax:
83
# .. autolink-skip:: [next|section|file|off]
84
85
class Skip(Directive):
86
"""
87
Skip auto-linking next code block.
88
89
Prevents the extension from processing specified code blocks,
90
useful for code that shouldn't have links or causes parsing issues.
91
"""
92
has_content = False
93
required_arguments = 0
94
optional_arguments = 1 # level: "next", "section", "file", "off"
95
```
96
97
### Directive Node Classes
98
99
Internal node classes used to represent directive markers in the document tree.
100
101
```python { .api }
102
class DeferredExamples(nodes.Element):
103
"""
104
Deferred node for substitution later when references are known.
105
106
Placeholder node that gets replaced with actual backreference
107
tables after all code has been analyzed.
108
"""
109
def __init__(self, ref: str, collapse: bool): ...
110
def copy(self): ...
111
112
class ConcatMarker(nodes.Element):
113
"""Marker for concatenation directives."""
114
def __init__(self, mode: str | None = None): ...
115
def copy(self): ...
116
117
class PrefaceMarker(nodes.Element):
118
"""Marker for preface directives."""
119
def __init__(self, content: str, level: str): ...
120
def copy(self): ...
121
122
class SkipMarker(nodes.Element):
123
"""Marker for skip directives."""
124
def __init__(self, level: str): ...
125
def copy(self): ...
126
```
127
128
### Visitor for Cleanup
129
130
Visitor class for removing directive nodes when the extension is disabled.
131
132
```python { .api }
133
class RemoveExtensionVisitor(nodes.SparseNodeVisitor):
134
"""
135
Silently remove all codeautolink directives.
136
137
Used when the extension is disabled or not generating HTML output,
138
removes directive markers that would otherwise appear as text.
139
"""
140
def unknown_departure(self, node) -> None: ...
141
def unknown_visit(self, node) -> None: ...
142
```
143
144
## Usage Examples
145
146
### Examples Directive Usage
147
148
Show where a class or function is used in documentation:
149
150
```rst
151
API Reference
152
=============
153
154
.. autoclass:: mymodule.MyClass
155
:members:
156
157
.. autolink-examples:: mymodule.MyClass
158
:collapse:
159
160
.. autolink-examples:: mymodule.my_function
161
:type: function
162
```
163
164
### Concatenation Control
165
166
Control how adjacent code blocks are linked together:
167
168
```rst
169
.. autolink-concat:: on
170
171
.. code-block:: python
172
173
import numpy as np
174
data = np.array([1, 2, 3])
175
176
.. code-block:: python
177
178
# This block sees 'data' from previous block
179
result = np.mean(data)
180
print(result)
181
182
.. autolink-concat:: off
183
184
.. code-block:: python
185
186
# This block starts fresh - no 'data' variable
187
new_data = [4, 5, 6]
188
```
189
190
### Preface Usage
191
192
Add hidden setup code for analysis:
193
194
```rst
195
.. autolink-preface::
196
import matplotlib.pyplot as plt
197
import numpy as np
198
199
.. code-block:: python
200
201
# The preface imports are available but not shown
202
x = np.linspace(0, 10, 100)
203
plt.plot(x, np.sin(x))
204
plt.show()
205
```
206
207
### Section-Level Preface
208
209
Apply preface to all code blocks in a section:
210
211
```rst
212
.. autolink-preface::
213
:level: section
214
215
import pandas as pd
216
import numpy as np
217
218
# Sample data for all examples
219
df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
220
221
Basic Operations
222
----------------
223
224
.. code-block:: python
225
226
# df is available from section preface
227
print(df.head())
228
229
.. code-block:: python
230
231
# Still available in this block too
232
result = df.mean()
233
```
234
235
### Skip Usage
236
237
Prevent linking on specific blocks:
238
239
```rst
240
.. autolink-skip::
241
242
.. code-block:: python
243
244
# This code won't get automatic links
245
# Useful for pseudocode or broken examples
246
somefunction() # Won't try to link 'somefunction'
247
248
.. code-block:: python
249
250
# Normal linking resumes here
251
import os
252
os.path.join('a', 'b') # 'import', 'os' will be linked
253
```
254
255
### Section-Level Skip
256
257
Skip linking for an entire section:
258
259
```rst
260
.. autolink-skip:: section
261
262
Pseudocode Examples
263
===================
264
265
.. code-block:: python
266
267
# No links in this section
268
abstract_function()
269
270
.. code-block:: python
271
272
# Also no links here
273
another_abstract_call()
274
```