0
# Content Creation Extensions
1

2
Enhanced directives and tools for creating rich documentation content including code blocks, examples, installation instructions, shields, and collapsible sections. These extensions provide modern documentation features that go beyond basic Sphinx capabilities.
3

4
## Capabilities
5

6
### Enhanced Code Blocks
7

8
Advanced code block directives with additional features like tab width control, execution counts, and Jupyter-style cells.
9

10
```python { .api }
11
class CodeBlock(SphinxDirective):
12
    """Enhanced code-block directive with adjustable tab width."""
13
    
14
    option_spec = {
15
        'linenos': directives.flag,
16
        'tab-width': directives.positive_int,
17
        'class': directives.class_option,
18
        # ... other standard code-block options
19
    }
20

21
class CodeCell(SphinxDirective):
22
    """Jupyter-style code block with execution count."""
23
    
24
    option_spec = {
25
        'execution-count': directives.positive_int,
26
        'linenos': directives.flag,
27
        'tab-width': directives.positive_int,
28
    }
29

30
class OutputCell(SphinxDirective):
31
    """Output cell variant of CodeCell for showing results."""
32
    
33
    option_spec = {
34
        'execution-count': directives.positive_int,
35
        'class': directives.class_option,
36
    }
37

38
class Prompt(Element):
39
    """Cell prompt node for CodeCell and OutputCell."""
40
```
41

42
Usage in reStructuredText:
43

44
```rst
45
.. code-block:: python
46
   :tab-width: 4
47
   :linenos:
48
   
49
   def example():
50
       return "Hello, World!"
51

52
.. code-cell:: python
53
   :execution-count: 1
54
   
55
   print("Hello from Jupyter-style cell!")
56

57
.. output-cell::
58
   :execution-count: 1
59
   
60
   Hello from Jupyter-style cell!
61
```
62

63
### Installation Instructions
64

65
Tabbed installation instructions supporting multiple package managers and installation methods.
66

67
```python { .api }
68
class InstallationDirective(SphinxDirective):
69
    """Creates tabbed installation instructions."""
70
    
71
    option_spec = {
72
        'pypi': directives.flag,
73
        'conda': directives.flag, 
74
        'github': directives.unchanged,
75
        'extra': directives.unchanged,
76
    }
77
    
78
    def run(self) -> List[Node]: ...
79
```
80

81
Usage:
82

83
```rst
84
.. installation:: package-name
85
   :pypi:
86
   :conda:
87
   :github: user/repo
88

89
.. installation:: complex-package
90
   :pypi:
91
   :extra: extra-requirements
92
```
93

94
### Shield and Badge Generation
95

96
Comprehensive shield/badge generation for project status, package information, and various metrics.
97

98
```python { .api }
99
# PyPI shields
100
class PyPIShieldDirective(SphinxDirective):
101
    """Generate PyPI package information shields."""
102

103
def make_pypi_shield(name: str, type_: str = "version") -> str:
104
    """
105
    Create PyPI shield URL.
106
    
107
    Args:
108
        name: Package name
109
        type_: Shield type ("version", "downloads", "license", etc.)
110
        
111
    Returns:
112
        Shield image URL
113
    """
114

115
# ReadTheDocs shields  
116
class RTFDShieldDirective(SphinxDirective):
117
    """Generate ReadTheDocs build status shields."""
118

119
def make_rtfd_shield(project: str) -> str:
120
    """
121
    Create ReadTheDocs shield URL.
122
    
123
    Args:
124
        project: ReadTheDocs project name
125
        
126
    Returns:
127
        Shield image URL
128
    """
129

130
# GitHub shields
131
class GitHubShieldDirective(SphinxDirective):
132
    """Generate GitHub repository shields."""
133

134
def make_github_shield(username: str, repository: str, type_: str = "stars") -> str:
135
    """
136
    Create GitHub shield URL.
137
    
138
    Args:
139
        username: GitHub username
140
        repository: Repository name  
141
        type_: Shield type ("stars", "forks", "issues", etc.)
142
        
143
    Returns:
144
        Shield image URL
145
    """
146

147
# Maintenance status
148
class MaintainedShieldDirective(SphinxDirective):
149
    """Generate maintenance status shields."""
150

151
# License shields
152
class LicenseShieldDirective(SphinxDirective):
153
    """Generate license shields."""
154

155
# And many more shield types...
156
```
157

158
Usage:
159

160
```rst
161
.. shields::
162
   :pypi:
163
   :github:
164
   :rtfd:
165
   :license:
166

167
.. pypi-shield:: package-name
168
   :alt: PyPI version
169

170
.. github-shield:: user/repo
171
   :type: stars
172
   :alt: GitHub stars
173
```
174

175
### reStructuredText Examples
176

177
Show reStructuredText source alongside its rendered output for documentation and tutorials.
178

179
```python { .api }
180
class reSTExampleDirective(SphinxDirective):
181
    """Shows reStructuredText source and rendered output side-by-side."""
182
    
183
    option_spec = {
184
        'no-trim': directives.flag,
185
        'class': directives.class_option,
186
    }
187

188
def make_rest_example(
189
    options: Dict[str, Any], 
190
    env: sphinx.environment.BuildEnvironment, 
191
    content: List[str]
192
) -> List[Node]:
193
    """
194
    Create rest example content nodes.
195
    
196
    Args:
197
        options: Directive options
198
        env: Sphinx build environment
199
        content: reStructuredText content lines
200
        
201
    Returns:
202
        List of nodes for source and rendered output
203
    """
204

205
# Node management
206
rest_example_purger: Purger
207
```
208

209
Usage:
210

211
```rst
212
.. rest-example::
213
   
214
   This is **bold** text and this is *italic* text.
215
   
216
   .. note::
217
      This is a note.
218
```
219

220
### Collapsible Content
221

222
Create collapsible content sections for better document organization.
223

224
```python { .api }
225
class CollapseDirective(SphinxDirective):
226
    """Creates collapsible content sections."""
227
    
228
    option_spec = {
229
        'class': directives.class_option,
230
        'open': directives.flag,
231
    }
232
    
233
    def run(self) -> List[Node]: ...
234
```
235

236
Usage:
237

238
```rst
239
.. collapse:: Click to expand
240
   :open:
241
   
242
   This content can be collapsed and expanded.
243
   
244
   It supports any reStructuredText content.
245
```
246

247
### Asset Links
248

249
Enhanced asset linking that opens files in browser instead of downloading.
250

251
```python { .api }
252
class AssetNode(Element):
253
    """Node representing links to assets."""
254

255
def asset_role(
256
    name: str, 
257
    rawtext: str, 
258
    text: str, 
259
    lineno: int, 
260
    inliner: Inliner, 
261
    options: Dict[str, Any] = {}, 
262
    content: List[str] = []
263
) -> Tuple[List[Node], List[system_message]]:
264
    """
265
    Role for linking to assets that open in browser.
266
    
267
    Args:
268
        name: Role name
269
        rawtext: Raw text content
270
        text: Asset path or URL
271
        lineno: Line number in source
272
        inliner: Sphinx inliner object
273
        options: Role options
274
        content: Role content
275
        
276
    Returns:
277
        Tuple of created nodes and system messages
278
    """
279

280
# Node visitors
281
def visit_asset_node(translator: HTML5Translator, node: AssetNode) -> None: ...
282
def depart_asset_node(translator: HTML5Translator, node: AssetNode) -> None: ...
283
```
284

285
Usage:
286

287
```rst
288
:asset:`path/to/document.pdf`
289
:asset:`https://example.com/image.png`
290
```
291

292
### CSS and Asset Management
293

294
Functions for managing CSS files and static assets in extensions.
295

296
```python { .api }
297
def copy_asset_files(app: Sphinx, exception: Optional[Exception]) -> None:
298
    """
299
    Copy CSS and other asset files to build output directory.
300
    
301
    Args:
302
        app: Sphinx application instance
303
        exception: Build exception if any occurred
304
    """
305

306
def configure(app: Sphinx, config: Config) -> None:
307
    """
308
    Configure LaTeX elements and other build settings.
309
    
310
    Args:
311
        app: Sphinx application instance
312
        config: Sphinx configuration object
313
    """
314
```
315

316
### Sidebar Links
317

318
Add navigation links to document sidebars.
319

320
```python { .api }
321
class SidebarLinksDirective(SphinxDirective):
322
    """Adds navigation links to sidebar."""
323
    
324
    option_spec = {
325
        'caption': directives.unchanged,
326
        'class': directives.class_option,
327
    }
328
    
329
    def run(self) -> List[Node]: ...
330
```
331

332
Usage:
333

334
```rst
335
.. sidebar-links::
336
   :caption: Quick Links
337
   
338
   * `Documentation <https://docs.example.com>`_
339
   * `GitHub <https://github.com/user/repo>`_
340
   * `Issues <https://github.com/user/repo/issues>`_
341
```
342

343
### Documentation Summary
344

345
Auto-generate documentation summaries and overviews.
346

347
```python { .api }
348
class DocumentationSummaryDirective(SphinxDirective):
349
    """Generates auto-generated documentation summaries."""
350
    
351
    option_spec = {
352
        'depth': directives.positive_int,
353
        'include': directives.unchanged,
354
        'exclude': directives.unchanged,
355
    }
356
    
357
    def run(self) -> List[Node]: ...
358
```
359

360
Usage:
361

362
```rst
363
.. documentation-summary::
364
   :depth: 2
365
   :include: api/*
366
   :exclude: internal/*
367
```
368

369
### Changeset Documentation
370

371
Track and document changes across versions with changeset directives.
372

373
```python { .api }
374
class ChangesetDirective(SphinxDirective):
375
    """Documents version changesets and release notes."""
376
    
377
    option_spec = {
378
        'version': directives.unchanged,
379
        'date': directives.unchanged,
380
        'type': directives.unchanged,  # 'added', 'changed', 'deprecated', 'removed', 'fixed', 'security'
381
    }
382
    
383
    def run(self) -> List[Node]: ...
384

385
def process_changesets(app: Sphinx, doctree: Element, docname: str) -> None:
386
    """Process changeset nodes for version tracking."""
387
```
388

389
Usage:
390

391
```rst
392
.. changeset:: 2.1.0
393
   :date: 2023-12-01
394
   :type: added
395
   
396
   * New feature for enhanced documentation
397
   * Added support for custom themes
398
   
399
.. changeset:: 2.1.0
400
   :type: fixed
401
   
402
   * Fixed issue with cross-references
403
   * Improved error handling
404
```
405

406
### Text Formatting Enhancements
407

408
Enhanced text formatting directives and roles for improved typography.
409

410
```python { .api }
411
class FormattingDirective(SphinxDirective):
412
    """Enhanced text formatting capabilities."""
413
    
414
    option_spec = {
415
        'style': directives.unchanged,
416
        'class': directives.class_option,
417
    }
418

419
# Formatting roles
420
def kbd_role() -> Tuple[List[Node], List[system_message]]  # :kbd: role for keyboard keys
421
def abbr_role() -> Tuple[List[Node], List[system_message]]  # :abbr: role for abbreviations  
422
def menuselection_role() -> Tuple[List[Node], List[system_message]]  # Enhanced menu selection
423
def guilabel_role() -> Tuple[List[Node], List[system_message]]  # Enhanced GUI label formatting
424
```
425

426
Usage:
427

428
```rst
429
Press :kbd:`Ctrl+C` to copy.
430
The :abbr:`API (Application Programming Interface)` is documented here.
431
Go to :menuselection:`File --> Open --> Recent Files` to access recent documents.
432
Click the :guilabel:`Save` button.
433
```