0
# ReStructuredText Tools
1

2
Clean HTML generation from ReStructuredText markup with minimal formatting output. These tools are designed for documentation systems, web publishing, and PyPI package descriptions that require clean, semantic HTML without extra div elements or CSS classes.
3

4
## Capabilities
5

6
### Clean HTML Generation
7

8
Convert ReStructuredText to clean HTML output without extra formatting elements.
9

10
```python { .api }
11
def rest2html(content: str, enable_exit_status: bool = None, **kwargs) -> str
12
```
13

14
**Parameters:**
15
- `content`: ReStructuredText markup to convert
16
- `enable_exit_status`: Enable docutils exit status reporting
17
- `**kwargs`: Additional docutils settings overrides
18

19
**Returns:** Clean HTML string
20

21
**Usage Examples:**
22

23
```python
24
from creole.rest_tools.clean_writer import rest2html
25

26
# Basic conversion
27
html = rest2html("This is **bold** text")
28
# Returns: '<p>This is <strong>bold</strong> text</p>\n'
29

30
# Convert bullet list
31
rest_content = """
32
- First item
33
- Second item  
34
- Third item
35
"""
36
html = rest2html(rest_content)
37
# Returns: '<ul>\n<li>First item</li>\n<li>Second item</li>\n<li>Third item</li>\n</ul>\n'
38

39
# Convert with link
40
html = rest2html("A link to `Example <http://example.com>`_ site")
41
# Returns: '<p>A link to <a href="http://example.com">Example</a> site</p>\n'
42

43
# Convert headings
44
rest_content = """
45
Main Title
46
==========
47

48
Subtitle
49
--------
50

51
Content here.
52
"""
53
html = rest2html(rest_content)
54
# Returns clean HTML with h1, h2 tags and paragraph
55
```
56

57
### PyPI-Compatible ReStructuredText Processing
58

59
Process ReStructuredText with PyPI-compatible restrictions for package descriptions.
60

61
```python { .api }
62
def pypi_rest2html(source: str, output_encoding: str = 'unicode') -> str
63
```
64

65
**Parameters:**
66
- `source`: ReStructuredText source text
67
- `output_encoding`: Output encoding (default: 'unicode')
68

69
**Returns:** HTML string compatible with PyPI rendering
70

71
**Usage Examples:**
72

73
```python
74
from creole.rest_tools.pypi_rest2html import pypi_rest2html
75

76
# Convert for PyPI compatibility
77
readme_rst = """
78
My Package
79
==========
80

81
This package does amazing things.
82

83
Features
84
--------
85

86
* Feature one
87
* Feature two
88
* Feature three
89
"""
90

91
html = pypi_rest2html(readme_rst)
92
# Returns HTML that matches PyPI's rendering rules
93
```
94

95
## Writer Classes
96

97
### Clean HTML Writer
98

99
Custom docutils writer that produces minimal HTML output.
100

101
```python { .api }
102
class CleanHTMLWriter:
103
    def __init__(self): ...
104
    def write(self, document, destination): ...
105

106
class CleanHTMLTranslator:
107
    def __init__(self, document): ...
108
    def visit_document(self, node): ...
109
    def depart_document(self, node): ...
110
```
111

112
**Usage Examples:**
113

114
```python
115
from creole.rest_tools.clean_writer import CleanHTMLWriter
116
from docutils.core import publish_parts
117

118
# Use custom writer directly
119
writer = CleanHTMLWriter()
120
parts = publish_parts(
121
    source="**bold text**",
122
    writer=writer,
123
    settings_overrides={
124
        "input_encoding": "unicode",
125
        "doctitle_xform": False,
126
    }
127
)
128
html = parts["html_body"]
129
```
130

131
## Configuration Options
132

133
The `rest2html` function accepts docutils configuration through keyword arguments:
134

135
```python
136
# Disable file insertion for security
137
html = rest2html(content, file_insertion_enabled=False)
138

139
# Disable raw HTML for security  
140
html = rest2html(content, raw_enabled=False)
141

142
# Custom settings
143
html = rest2html(content, 
144
                doctitle_xform=False,
145
                initial_header_level=2,
146
                report_level=2)
147
```
148

149
## Security Considerations
150

151
By default, `rest2html` disables potentially dangerous docutils features:
152
- `file_insertion_enabled=False`: Prevents file inclusion directives
153
- `raw_enabled=False`: Prevents raw HTML/LaTeX inclusion
154

155
These settings make it safe to process untrusted ReStructuredText content.
156

157
## Error Handling
158

159
The function validates input as Unicode strings and will raise `AssertionError` for non-string input. Docutils parsing errors are handled according to the `enable_exit_status` parameter:
160

161
- `None` (default): Suppress docutils exit status
162
- `True`: Allow docutils to exit on severe errors
163
- `False`: Convert errors to exceptions
164

165
For testing and validation, you can enable strict error reporting:
166

167
```python
168
try:
169
    html = rest2html(malformed_rst, enable_exit_status=True)
170
except SystemExit as e:
171
    print(f"ReStructuredText error: exit code {e.code}")
172
```