0
# rinohtype
1

2
A comprehensive Python document processing library that renders structured documents to PDF with advanced typography, customizable styling, and professional layout capabilities. rinohtype enables creation of high-quality PDFs from reStructuredText, CommonMark, and Sphinx sources with extensive control over document appearance and structure.
3

4
## Package Information
5

6
- **Package Name**: rinohtype
7
- **Language**: Python
8
- **Installation**: `pip install rinohtype`
9

10
## Core Imports
11

12
```python
13
import rinohtype
14
```
15

16
Common for document processing:
17

18
```python
19
from rinohtype import Document, DocumentTree, StyleSheet
20
from rinohtype import Paragraph, Section, Heading, List, Table
21
from rinohtype import Style, Dimension, Color
22
```
23

24
For specific functionality:
25

26
```python
27
# Template system
28
from rinohtype.template import Article, Book, DocumentTemplate
29

30
# Styling system  
31
from rinohtype.style import StyleSheet, Style
32
from rinohtype.stylesheets import sphinx
33

34
# Layout and flowables
35
from rinohtype.flowable import Flowable, GroupedFlowables
36
from rinohtype.structure import Section, Heading, List, Table
37
from rinohtype.paragraph import Paragraph
38
from rinohtype.image import Image, Figure
39

40
# Typography and formatting
41
from rinohtype.font import Typeface, Font
42
from rinohtype.color import Color, HexColor, BLACK, WHITE
43
from rinohtype.dimension import Dimension, PT, MM, CM, INCH
44
```
45

46
## Basic Usage
47

48
```python
49
from rinohtype import Document, DocumentTree, StyleSheet
50
from rinohtype.structure import Section, Heading
51
from rinohtype.paragraph import Paragraph
52
from rinohtype.template import Article
53
from rinohtype.stylesheets import sphinx
54
from rinohtype.backend import pdf
55

56
# Create document content
57
heading = Heading("Document Title")
58
content = Paragraph("This is the main content of the document.")
59
section = Section([heading, content])
60

61
# Build document tree
62
doc_tree = DocumentTree([section])
63

64
# Create document with template and stylesheet
65
template = Article()
66
stylesheet = sphinx
67
document = Document(doc_tree, stylesheet, template)
68

69
# Render to PDF
70
document.render('output')  # Creates output.pdf
71
```
72

73
More complex example with styling:
74

75
```python
76
from rinohtype import *
77
from rinohtype.style import Style
78
from rinohtype.color import Color
79
from rinohtype.dimension import PT
80

81
# Create custom styles
82
title_style = Style(font_size=16*PT, font_weight='bold', 
83
                   text_color=Color(0, 0, 0.8))
84
body_style = Style(font_size=11*PT, line_spacing=1.2)
85

86
# Create styled content
87
title = Heading("Custom Document", style=title_style)
88
paragraph = Paragraph("Content with custom styling.", style=body_style)
89

90
# Build and render document
91
doc_tree = DocumentTree([Section([title, paragraph])])
92
document = Document(doc_tree, stylesheet=sphinx)
93
document.render('styled_output')
94
```
95

96
## Architecture
97

98
rinohtype uses a layered architecture for flexible document processing:
99

100
- **Document Tree**: Hierarchical content structure with flowables and elements
101
- **Template System**: Page layout, headers/footers, and document structure templates
102
- **Style System**: CSS-like styling with inheritance, selectors, and attribute validation
103
- **Layout Engine**: Container-based layout with automatic text flow and pagination
104
- **Typography Engine**: Advanced text rendering with font management and OpenType features
105
- **Backend System**: Pluggable output backends (currently PDF via ReportLab)
106

107
The core workflow: Content → Styling → Layout → Rendering → Output
108

109
## Capabilities
110

111
### Document Structure
112

113
Core document building blocks including sections, headings, paragraphs, lists, tables, and hierarchical content organization.
114

115
```python { .api }
116
class Section(Flowable):
117
    def __init__(self, flowables, id=None, style=None, parent=None, source=None): ...
118

119
class Heading(Paragraph):
120
    def __init__(self, content, id=None, style=None, parent=None, source=None): ...
121

122
class Paragraph(Flowable):
123
    def __init__(self, text_or_flowables, id=None, style=None, parent=None, source=None): ...
124

125
class List(Flowable): ...
126
class ListItem(Flowable): ...
127
class Table(Flowable): ...
128
```
129

130
[Document Structure](./document-structure.md)
131

132
### Styling System
133

134
Comprehensive styling framework with CSS-like selectors, inheritance, attribute validation, and stylesheet management.
135

136
```python { .api }
137
class Style(AttributesDictionary):
138
    def __init__(self, base=None, **attributes): ...
139

140
class StyleSheet(dict):
141
    def __init__(self, name, base=None, matcher=None): ...
142

143
class Styled(DocumentElement):
144
    style = Attribute(Style): ...
145
```
146

147
[Styling System](./styling-system.md)
148

149
### Layout Engine
150

151
Advanced layout system with container management, text flow, pagination, and automatic element positioning.
152

153
```python { .api }
154
class Container:
155
    def __init__(self, name, parent, left=None, top=None, width=None, height=None): ...
156
    def render(self, flowable, last_descender=None): ...
157
    def advance(self, height): ...
158

159
class Flowable(Styled):
160
    def flow(self, container, last_descender, state=None): ...
161
    def render(self, container, descender, state=None, first_line_only=False): ...
162
```
163

164
[Layout Engine](./layout-engine.md)
165

166
### Typography and Text
167

168
Advanced text processing including font management, text styling, inline elements, and OpenType features.
169

170
```python { .api }
171
class Font:
172
    def __init__(self, typeface, weight=MEDIUM, width=NORMAL, slant=UPRIGHT): ...
173

174
class Typeface:
175
    def __init__(self, name, *fonts): ...
176

177
class StyledText(InlineFlowable):
178
    def __init__(self, text, style=None, parent=None): ...
179

180
class TextStyle(Style): ...
181
```
182

183
[Typography and Text](./typography-text.md)
184

185
### Graphics and Images
186

187
Image handling, drawing primitives, shapes, colors, and graphical elements for rich document content.
188

189
```python { .api }
190
class Image(Flowable):
191
    def __init__(self, filename_or_file, scale=1.0, width=None, height=None, dpi=None): ...
192

193
class Figure(Float):
194
    def __init__(self, image_or_flowable, caption=None, id=None, style=None): ...
195

196
class Color:
197
    def __init__(self, red, green, blue, alpha=1): ...
198

199
class Rectangle(Shape):
200
    def __init__(self, bottom_left, width, height, style=None, parent=None): ...
201
```
202

203
[Graphics and Images](./graphics-images.md)
204

205
### Template System
206

207
Document templates, page layouts, headers/footers, and document structure configuration.
208

209
```python { .api }
210
class DocumentTemplate(TemplateConfiguration):
211
    def __init__(self, name=None, configuration=None): ...
212

213
class Article(DocumentTemplate): ...
214
class Book(DocumentTemplate): ...
215

216
class PageTemplate:
217
    def __init__(self, name, page_size, page_orientation='portrait'): ...
218
```
219

220
[Template System](./template-system.md)
221

222
### References and Cross-References
223

224
Cross-reference system including footnotes, endnotes, table of contents, index, and internal linking.
225

226
```python { .api }
227
class Reference(InlineFlowable):
228
    def __init__(self, target, reference_type='reference', style=None): ...
229

230
class Note(GroupedFlowables):
231
    def __init__(self, note_flowables, id=None, style=None, parent=None): ...
232

233
class TableOfContents(Section): ...
234
class Index(Section): ...
235
```
236

237
[References and Cross-References](./references.md)
238

239
### Dimensions and Measurements
240

241
Comprehensive measurement system with units, calculations, and layout dimensions.
242

243
```python { .api }
244
class Dimension:
245
    def __init__(self, value=0, unit=None): ...
246
    def to_points(self, total_dimension=None): ...
247

248
# Unit constants
249
PT = <DimensionUnit>    # Points (1/72 inch)
250
MM = <DimensionUnit>    # Millimeters  
251
CM = <DimensionUnit>    # Centimeters
252
INCH = <DimensionUnit>  # Inches
253
PERCENT = <DimensionUnit>  # Percentage
254
```
255

256
[Dimensions and Measurements](./dimensions.md)
257

258
## Error Handling
259

260
rinohtype provides several exception types for different error conditions:
261

262
- **ResourceNotFound**: Raised when fonts, images, or other resources cannot be found
263
- **ParseError**: Raised when parsing configuration files or style definitions fails  
264
- **ContainerOverflow**: Raised during layout when content doesn't fit in available space
265
- **InlineFlowableException**: Raised for inline element rendering issues
266

267
Common error scenarios include missing font files, invalid style definitions, and layout overflow conditions.