0
# Docutils Integration
1

2
Standalone docutils parser and renderer for direct notebook processing without Sphinx, enabling integration into custom documentation pipelines. This provides MyST-NB functionality outside of the Sphinx ecosystem.
3

4
## Capabilities
5

6
### Docutils Parser
7

8
Main parser class for processing notebooks in standalone docutils applications.
9

10
```python { .api }
11
class Parser(MystParser):
12
    """
13
    Docutils parser for MyST notebooks.
14
    
15
    Extends MystParser to handle notebook content in docutils
16
    processing pipelines without requiring Sphinx.
17
    """
18
    
19
    def parse(self, inputstring: str, document: nodes.document) -> None:
20
        """
21
        Parse notebook content into docutils document tree.
22
        
23
        Parameters:
24
        - inputstring: str - Raw notebook or MyST content
25
        - document: nodes.document - Target docutils document
26
        """
27
```
28

29
### Docutils Renderer
30

31
Renderer class specifically designed for docutils output formats.
32

33
```python { .api }
34
class DocutilsNbRenderer(DocutilsRenderer, MditRenderMixin):
35
    """
36
    Docutils notebook renderer.
37
    
38
    Combines DocutilsRenderer capabilities with notebook-specific
39
    rendering via MditRenderMixin for standalone docutils processing.
40
    """
41
    
42
    def render_nb_cell_code(self, cell, **kwargs):
43
        """Render code cells for docutils output."""
44
        pass
45
        
46
    def render_nb_cell_markdown(self, cell, **kwargs):
47
        """Render markdown cells for docutils output."""
48
        pass
49
```
50

51
### Docutils Application Container
52

53
Container class for managing docutils roles and directives in MyST-NB context.
54

55
```python { .api }
56
class DocutilsApp:
57
    """
58
    Container for docutils roles and directives.
59
    
60
    Provides a Sphinx-like application interface for registering
61
    and managing MyST-NB extensions in docutils-only environments.
62
    """
63
    
64
    def add_role(self, name: str, role_func: Callable) -> None:
65
        """Register a docutils role."""
66
        pass
67
        
68
    def add_directive(self, name: str, directive_class: type) -> None:
69
        """Register a docutils directive."""
70
        pass
71
```
72

73
## CLI Functions
74

75
### HTML Generation
76

77
Generate HTML output from notebooks using docutils backend.
78

79
```python { .api }
80
def cli_html(args: list[str] | None = None) -> None:
81
    """
82
    Generate HTML output from notebook using docutils.
83
    
84
    Parameters:
85
    - args: Optional command-line arguments for HTML generation
86
    
87
    Command-line interface for converting notebooks to HTML
88
    without requiring Sphinx installation.
89
    """
90
```
91

92
### HTML5 Generation
93

94
Generate modern HTML5 output with enhanced features.
95

96
```python { .api }
97
def cli_html5(args: list[str] | None = None) -> None:
98
    """
99
    Generate HTML5 output from notebook using docutils.
100
    
101
    Parameters:
102
    - args: Optional command-line arguments for HTML5 generation
103
    
104
    Produces HTML5 output with modern web standards and features.
105
    """
106
```
107

108
### LaTeX Generation
109

110
Generate LaTeX output suitable for PDF compilation.
111

112
```python { .api }
113
def cli_latex(args: list[str] | None = None) -> None:
114
    """
115
    Generate LaTeX output from notebook using docutils.
116
    
117
    Parameters:
118
    - args: Optional command-line arguments for LaTeX generation
119
    
120
    Converts notebook content to LaTeX format for academic
121
    and publication-quality document generation.
122
    """
123
```
124

125
### XML Generation
126

127
Generate structured XML output for data processing.
128

129
```python { .api }
130
def cli_xml(args: list[str] | None = None) -> None:
131
    """
132
    Generate XML output from notebook using docutils.
133
    
134
    Parameters:
135
    - args: Optional command-line arguments for XML generation
136
    
137
    Produces structured XML representation of notebook content
138
    suitable for further processing or data exchange.
139
    """
140
```
141

142
### Debug Output
143

144
Generate pseudo-XML for debugging document structure.
145

146
```python { .api }
147
def cli_pseudoxml(args: list[str] | None = None) -> None:
148
    """
149
    Generate pseudo-XML output for debugging document structure.
150
    
151
    Parameters:
152
    - args: Optional command-line arguments for pseudo-XML generation
153
    
154
    Creates human-readable pseudo-XML showing the internal
155
    document tree structure for debugging purposes.
156
    """
157
```
158

159
## Usage Examples
160

161
### Basic Docutils Processing
162

163
```python
164
from myst_nb.docutils_ import Parser, DocutilsNbRenderer
165
from docutils.core import publish_parts
166
from myst_nb.core.config import NbParserConfig
167

168
# Setup parser and renderer
169
config = NbParserConfig()
170
parser = Parser(config=config)
171
renderer = DocutilsNbRenderer()
172

173
# Process notebook content
174
with open("notebook.md", "r") as f:
175
    content = f.read()
176

177
# Generate HTML using docutils
178
parts = publish_parts(
179
    content,
180
    parser=parser,
181
    writer_name="html5"
182
)
183

184
html_output = parts['html_body']
185
print(html_output)
186
```
187

188
### Custom Docutils Pipeline
189

190
```python
191
from myst_nb.docutils_ import Parser, DocutilsApp
192
from docutils import nodes
193
from docutils.parsers.rst import directives
194

195
# Create docutils application
196
app = DocutilsApp()
197

198
# Register custom directive
199
class CustomDirective(directives.Directive):
200
    def run(self):
201
        return [nodes.paragraph(text="Custom content")]
202

203
app.add_directive("custom", CustomDirective)
204

205
# Setup parser with custom app
206
parser = Parser(app=app)
207

208
# Process content with custom extensions
209
content = """
210
# My Notebook
211

212
```{custom}
213
```
214

215
```{code-cell} python
216
print("Hello from MyST-NB!")
217
```
218
"""
219

220
# Convert to various formats
221
from docutils.core import publish_string
222

223
# Generate HTML
224
html = publish_string(content, parser=parser, writer_name="html5")
225

226
# Generate LaTeX
227
latex = publish_string(content, parser=parser, writer_name="latex")
228
```
229
230
### Batch Document Processing
231

232
```python
233
import os
234
from pathlib import Path
235
from myst_nb.docutils_ import cli_html, cli_latex
236

237
def batch_convert_notebooks(input_dir, output_dir, format="html"):
238
    """Convert all notebooks in directory to specified format."""
239
    input_path = Path(input_dir)
240
    output_path = Path(output_dir)
241
    output_path.mkdir(exist_ok=True)
242
    
243
    # Find all notebook files
244
    for nb_file in input_path.glob("*.md"):
245
        output_file = output_path / f"{nb_file.stem}.{format}"
246
        
247
        # Convert based on format
248
        if format == "html":
249
            cli_html([str(nb_file), str(output_file)])
250
        elif format == "latex":
251
            cli_latex([str(nb_file), str(output_file)])
252
        
253
        print(f"Converted: {nb_file} -> {output_file}")
254

255
# Usage
256
batch_convert_notebooks("notebooks/", "output/html/", "html")
257
batch_convert_notebooks("notebooks/", "output/latex/", "latex")
258
```
259

260
### Integration with Build Systems
261

262
```python
263
import subprocess
264
from myst_nb.docutils_ import DocutilsApp, Parser
265

266
class NotebookProcessor:
267
    """Notebook processor for build systems."""
268
    
269
    def __init__(self, config):
270
        self.config = config
271
        self.app = DocutilsApp()
272
        self.parser = Parser(config=config, app=self.app)
273
    
274
    def process_file(self, input_file, output_file, format="html"):
275
        """Process single notebook file."""
276
        try:
277
            # Use CLI functions for processing
278
            if format == "html":
279
                from myst_nb.docutils_ import cli_html
280
                cli_html([input_file, output_file])
281
            elif format == "latex":
282
                from myst_nb.docutils_ import cli_latex
283
                cli_latex([input_file, output_file])
284
            
285
            return True
286
        except Exception as e:
287
            print(f"Error processing {input_file}: {e}")
288
            return False
289
    
290
    def process_directory(self, input_dir, output_dir, format="html"):
291
        """Process all notebooks in directory."""
292
        success_count = 0
293
        error_count = 0
294
        
295
        for nb_file in Path(input_dir).glob("*.md"):
296
            output_file = Path(output_dir) / f"{nb_file.stem}.{format}"
297
            
298
            if self.process_file(str(nb_file), str(output_file), format):
299
                success_count += 1
300
            else:
301
                error_count += 1
302
        
303
        print(f"Processed: {success_count} success, {error_count} errors")
304
        return success_count, error_count
305

306
# Usage in build script
307
from myst_nb.core.config import NbParserConfig
308

309
config = NbParserConfig(
310
    execution_mode="auto",
311
    remove_code_source=False
312
)
313

314
processor = NotebookProcessor(config)
315
processor.process_directory("src/", "build/html/", "html")
316
```
317

318
### Custom Writer Integration
319

320
```python
321
from docutils import writers, nodes
322
from myst_nb.docutils_ import Parser
323

324
class CustomWriter(writers.Writer):
325
    """Custom writer for specialized output format."""
326
    
327
    def __init__(self):
328
        writers.Writer.__init__(self)
329
        self.translator_class = CustomTranslator
330
    
331
    def translate(self):
332
        self.visitor = self.translator_class(self.document)
333
        self.document.walkabout(self.visitor)
334
        self.output = self.visitor.astext()
335

336
class CustomTranslator(nodes.NodeVisitor):
337
    """Custom translator for notebook elements."""
338
    
339
    def __init__(self, document):
340
        nodes.NodeVisitor.__init__(self, document)
341
        self.body = []
342
    
343
    def visit_paragraph(self, node):
344
        self.body.append('<p>')
345
    
346
    def depart_paragraph(self, node):
347
        self.body.append('</p>\n')
348
    
349
    def astext(self):
350
        return ''.join(self.body)
351

352
# Register and use custom writer
353
writers.register_writer('custom', CustomWriter)
354

355
# Process with custom writer
356
from docutils.core import publish_string
357

358
content = """
359
# My Notebook
360

361
This is a paragraph.
362

363
```{code-cell} python
364
print("Hello, World!")
365
```
366
"""
367

368
output = publish_string(
369
    content, 
370
    parser=Parser(),
371
    writer_name='custom'
372
)
373
```
374

375
The docutils integration provides complete MyST-NB functionality outside of Sphinx, enabling integration into custom documentation pipelines, build systems, and standalone processing workflows.