0
# Inventory and Warning Systems
1
2
Sphinx inventory integration for cross-references and comprehensive warning system with categorized warning types for parsing, rendering, and reference resolution issues.
3
4
## Capabilities
5
6
### Sphinx Inventory Integration
7
8
Complete integration with Sphinx's inventory system for cross-document and cross-project reference resolution, supporting loading, conversion, and manipulation of inventory data.
9
10
```python { .api }
11
def from_sphinx(inv) -> InventoryType:
12
"""
13
Convert from Sphinx inventory format to MyST format.
14
15
Args:
16
inv: Sphinx inventory object
17
18
Returns:
19
MyST-compatible inventory dictionary
20
"""
21
22
def to_sphinx(inv: InventoryType):
23
"""
24
Convert MyST inventory to Sphinx inventory format.
25
26
Args:
27
inv: MyST inventory dictionary
28
29
Returns:
30
Sphinx-compatible inventory object
31
"""
32
33
def load(stream, base_url: str) -> InventoryType:
34
"""
35
Load inventory from stream with base URL resolution.
36
37
Args:
38
stream: Input stream containing inventory data
39
base_url: Base URL for resolving relative references
40
41
Returns:
42
Loaded inventory dictionary
43
44
Raises:
45
InventoryLoadError: When inventory loading fails
46
"""
47
```
48
49
Usage example:
50
51
```python
52
from myst_parser.inventory import from_sphinx, to_sphinx, load
53
import urllib.request
54
55
# Load inventory from URL
56
with urllib.request.urlopen("https://docs.python.org/3/objects.inv") as stream:
57
python_inv = load(stream, "https://docs.python.org/3/")
58
59
print(f"Loaded {len(python_inv['items'])} items from Python inventory")
60
61
# Access inventory items
62
for name, item in python_inv['items'].items():
63
if 'dict' in name.lower():
64
print(f"{item['name']}: {item['uri']}")
65
66
# Convert between formats
67
sphinx_inv = to_sphinx(python_inv)
68
myst_inv = from_sphinx(sphinx_inv)
69
```
70
71
### Inventory Data Structures
72
73
Type-safe data structures for representing Sphinx inventory information with full type annotations and validation.
74
75
```python { .api }
76
class InventoryItemType(TypedDict):
77
"""
78
A single inventory item.
79
80
Attributes:
81
loc: The location of the item (relative if base_url not None)
82
text: Implicit text to show for the item (None for no text)
83
"""
84
loc: str
85
text: str | None
86
87
class InventoryType(TypedDict):
88
"""
89
Inventory data.
90
91
Attributes:
92
name: The name of the project
93
version: The version of the project
94
base_url: The base URL of the loc
95
objects: Mapping of domain -> object type -> name -> item
96
"""
97
name: str
98
version: str
99
base_url: str | None
100
objects: dict[str, dict[str, dict[str, InventoryItemType]]]
101
```
102
103
Usage example:
104
105
```python
106
from myst_parser.inventory import InventoryType, InventoryItemType
107
108
# Create inventory item
109
item: InventoryItemType = {
110
"loc": "library/stdtypes.html#dict.get",
111
"text": "dict.get"
112
}
113
114
# Create inventory
115
inventory: InventoryType = {
116
"name": "Python",
117
"version": "3.11",
118
"base_url": "https://docs.python.org/3/",
119
"objects": {
120
"py": {
121
"method": {
122
"dict.get": item
123
}
124
}
125
}
126
}
127
128
# Access typed data
129
for domain, obj_types in inventory["objects"].items():
130
for obj_type, objects in obj_types.items():
131
for name, item in objects.items():
132
print(f"{domain}:{obj_type}:{name} -> {item['loc']}")
133
```
134
135
### Warning System
136
137
Comprehensive warning system with categorized warning types for different aspects of MyST parsing, rendering, and cross-reference resolution.
138
139
```python { .api }
140
class MystWarnings(Enum):
141
"""
142
Enumeration of MyST warning types with descriptive values.
143
144
Categories:
145
- General: DEPRECATED, NOT_SUPPORTED, RENDER_METHOD
146
- Markdown: MD_TOPMATTER, MD_DEF_DUPE, MD_HEADING_NON_CONSECUTIVE
147
- Directives: DIRECTIVE_PARSING, DIRECTIVE_OPTION, DIRECTIVE_BODY, UNKNOWN_DIRECTIVE, UNKNOWN_ROLE
148
- Cross-references: XREF_AMBIGUOUS, XREF_MISSING, IREF_MISSING, IREF_AMBIGUOUS
149
- Inventory: INV_LOAD, LEGACY_DOMAIN
150
- Extensions: HEADING_SLUG, STRIKETHROUGH, HTML_PARSE, INVALID_ATTRIBUTE, SUBSTITUTION
151
"""
152
153
# General warnings
154
DEPRECATED = "deprecated"
155
NOT_SUPPORTED = "not_supported"
156
RENDER_METHOD = "render"
157
158
# Markdown parsing warnings
159
MD_TOPMATTER = "topmatter"
160
MD_DEF_DUPE = "duplicate_def"
161
MD_HEADING_NON_CONSECUTIVE = "header"
162
163
# Directive warnings
164
DIRECTIVE_PARSING = "directive_parse"
165
DIRECTIVE_OPTION = "directive_option"
166
DIRECTIVE_BODY = "directive_body"
167
UNKNOWN_DIRECTIVE = "directive_unknown"
168
UNKNOWN_ROLE = "role_unknown"
169
170
# Cross-reference warnings
171
XREF_AMBIGUOUS = "xref_ambiguous"
172
XREF_MISSING = "xref_missing"
173
IREF_MISSING = "iref_missing"
174
IREF_AMBIGUOUS = "iref_ambiguous"
175
176
# Inventory warnings
177
INV_LOAD = "inv_retrieval"
178
LEGACY_DOMAIN = "domains"
179
180
# Extension warnings
181
HEADING_SLUG = "heading_slug"
182
STRIKETHROUGH = "strikethrough"
183
HTML_PARSE = "html"
184
INVALID_ATTRIBUTE = "attribute"
185
SUBSTITUTION = "substitution"
186
187
def create_warning(
188
document,
189
message: str,
190
subtype: MystWarnings = MystWarnings.RENDER_METHOD,
191
line: int | None = None,
192
append_to: list | None = None,
193
**kwargs
194
) -> None:
195
"""
196
Generate warning with logging and optional collection.
197
198
Args:
199
document: Docutils document context
200
message: Warning message text
201
subtype: Warning category from MystWarnings enum
202
line: Source line number (optional)
203
append_to: List to append warning to (optional)
204
**kwargs: Additional warning context
205
"""
206
207
def _is_suppressed_warning(
208
type: str,
209
subtype: MystWarnings,
210
suppress_warnings: list[str]
211
) -> bool:
212
"""
213
Check if warning should be suppressed based on configuration.
214
215
Args:
216
type: Warning type identifier
217
subtype: Warning subtype from MystWarnings enum
218
suppress_warnings: List of suppressed warning patterns
219
220
Returns:
221
True if warning should be suppressed
222
"""
223
```
224
225
Usage example:
226
227
```python
228
from myst_parser.warnings_ import create_warning, MystWarnings, _is_suppressed_warning
229
from docutils.utils import new_document
230
231
# Create document for warning context
232
document = new_document('<string>')
233
234
# Generate different types of warnings
235
create_warning(
236
document,
237
"Unknown directive 'custom-block'",
238
subtype=MystWarnings.UNKNOWN_DIRECTIVE,
239
line=15
240
)
241
242
create_warning(
243
document,
244
"Cross-reference target 'missing-section' not found",
245
subtype=MystWarnings.XREF_MISSING,
246
line=23
247
)
248
249
create_warning(
250
document,
251
"Invalid YAML in frontmatter",
252
subtype=MystWarnings.MD_TOPMATTER,
253
line=3
254
)
255
256
# Check warning suppression
257
suppress_list = ["myst.xref_missing", "myst.unknown_directive"]
258
259
is_suppressed = _is_suppressed_warning(
260
"myst",
261
MystWarnings.XREF_MISSING,
262
suppress_list
263
)
264
print(f"XREF_MISSING suppressed: {is_suppressed}") # True
265
```
266
267
### Warning Collection and Reporting
268
269
Advanced warning collection and reporting capabilities for batch processing and analysis of MyST documents.
270
271
```python { .api }
272
class WarningCollector:
273
"""
274
Collector for aggregating warnings during document processing.
275
276
Provides functionality to collect, categorize, and report warnings
277
from multiple documents or processing stages.
278
"""
279
280
def __init__(self): ...
281
282
def add_warning(
283
self,
284
message: str,
285
subtype: MystWarnings,
286
source: str | None = None,
287
line: int | None = None
288
) -> None: ...
289
290
def get_warnings_by_type(self, subtype: MystWarnings) -> list: ...
291
292
def get_warnings_by_source(self, source: str) -> list: ...
293
294
def generate_report(self, format: str = "text") -> str: ...
295
296
def collect_warnings_from_document(document) -> list[dict]:
297
"""
298
Extract all warnings from a processed document.
299
300
Args:
301
document: Docutils document that may contain warnings
302
303
Returns:
304
List of warning dictionaries with metadata
305
"""
306
```
307
308
Usage example:
309
310
```python
311
from myst_parser.warnings_ import WarningCollector, MystWarnings
312
313
# Create warning collector
314
collector = WarningCollector()
315
316
# Process multiple documents
317
for doc_path in ["doc1.md", "doc2.md", "doc3.md"]:
318
try:
319
# ... process document ...
320
pass
321
except Exception as e:
322
collector.add_warning(
323
f"Processing failed: {e}",
324
MystWarnings.RENDER_METHOD,
325
source=doc_path
326
)
327
328
# Generate summary report
329
report = collector.generate_report("text")
330
print(report)
331
332
# Get specific warning types
333
xref_warnings = collector.get_warnings_by_type(MystWarnings.XREF_MISSING)
334
print(f"Found {len(xref_warnings)} missing cross-references")
335
```
336
337
### Warning Configuration
338
339
Configuration options for controlling warning behavior in Sphinx and standalone environments.
340
341
```python
342
# Sphinx configuration (conf.py)
343
suppress_warnings = [
344
"myst.header", # Suppress header warnings
345
"myst.xref_missing", # Suppress missing cross-reference warnings
346
"myst.unknown_directive", # Suppress unknown directive warnings
347
]
348
349
# MyST-specific warning configuration
350
myst_suppress_warnings = [
351
"md_topmatter", # YAML frontmatter warnings
352
"directive_parsing", # Directive parsing warnings
353
"html_unknown_tag", # Unknown HTML tag warnings
354
]
355
356
# Warning level configuration
357
myst_warning_as_error = [
358
"xref_missing", # Treat missing refs as errors
359
"unknown_directive" # Treat unknown directives as errors
360
]
361
```
362
363
Usage in Sphinx:
364
365
```python
366
# In conf.py
367
extensions = ['myst_parser']
368
369
# Configure warning suppression
370
suppress_warnings = [
371
'myst.xref_missing',
372
'myst.unknown_directive'
373
]
374
375
# MyST-specific warning control
376
myst_suppress_warnings = [
377
'md_topmatter',
378
'directive_parsing'
379
]
380
```
381
382
## Inventory File Formats
383
384
MyST-Parser supports multiple inventory file formats:
385
386
### Standard Sphinx Format
387
388
```python
389
# Binary Sphinx inventory format
390
# Loaded with inventory.load() from objects.inv files
391
inventory = load(stream, "https://docs.python.org/3/")
392
```
393
394
### JSON Format
395
396
```json
397
{
398
"project": "Python",
399
"version": "3.11",
400
"items": {
401
"py:class:dict": {
402
"name": "dict",
403
"domain": "py",
404
"role": "class",
405
"uri": "library/stdtypes.html#dict",
406
"dispname": "dict"
407
}
408
}
409
}
410
```
411
412
### YAML Format
413
414
```yaml
415
project: Python
416
version: "3.11"
417
items:
418
py:class:dict:
419
name: dict
420
domain: py
421
role: class
422
uri: library/stdtypes.html#dict
423
dispname: dict
424
```
425
426
## Types
427
428
Inventory and warning system type definitions:
429
430
```python { .api }
431
class InventoryItemType(TypedDict):
432
"""Single inventory item with required fields."""
433
name: str
434
domain: str
435
role: str
436
uri: str
437
dispname: str
438
439
class InventoryType(TypedDict):
440
"""Complete inventory structure."""
441
project: str
442
version: str
443
items: dict[str, InventoryItemType]
444
445
class MystWarnings(Enum):
446
"""Enumeration of all MyST warning categories."""
447
448
class WarningCollector:
449
"""Warning collection and reporting system."""
450
451
# Exception types
452
class InventoryLoadError(Exception):
453
"""Raised when inventory loading fails."""
454
455
class WarningError(Exception):
456
"""Raised when warnings are treated as errors."""
457
```