0
# Document Structure
1

2
Core document building blocks that form the hierarchical content structure of rinohtype documents. These elements provide the foundation for creating well-organized, professional documents with proper semantic structure.
3

4
## Capabilities
5

6
### Document Tree
7

8
The root container that holds all document content and manages the overall document structure.
9

10
```python { .api }
11
class DocumentTree(StaticGroupedFlowables):
12
    """
13
    Root document content container.
14
    
15
    Parameters:
16
    - flowables: list of Flowable objects representing document content
17
    - options: dict, optional document-level options
18
    - style: Style object for document-level styling
19
    - source: source location information
20
    """
21
    def __init__(self, flowables, options=None, style=None, source=None): ...
22
```
23

24
### Sections
25

26
Hierarchical document sections that organize content into logical groups with automatic numbering and table of contents integration.
27

28
```python { .api }
29
class Section(StaticGroupedFlowables):
30
    """
31
    Document section containing flowables with hierarchical organization.
32
    
33
    Parameters:
34
    - flowables: list of Flowable objects in this section
35
    - id: str, unique identifier for cross-referencing
36
    - style: Style object for section formatting
37
    - parent: parent element
38
    - source: source location information
39
    """
40
    def __init__(self, flowables, id=None, style=None, parent=None, source=None): ...
41
    
42
    @property
43
    def level(self): ...  # Section nesting level
44
```
45

46
### Headings
47

48
Section titles with automatic numbering, table of contents integration, and hierarchical styling.
49

50
```python { .api }
51
class Heading(StaticParagraph):
52
    """
53
    Section heading with automatic numbering and TOC integration.
54
    
55
    Parameters:
56
    - content: str or list of inline elements for heading text
57
    - id: str, unique identifier for cross-referencing
58
    - style: Style object for heading appearance
59
    - parent: parent element (typically Section)
60
    - source: source location information
61
    """
62
    def __init__(self, content, id=None, style=None, parent=None, source=None): ...
63
    
64
    @property
65
    def section(self): ...  # Parent section
66
    
67
    @property
68
    def level(self): ...  # Heading level (1-6)
69
```
70

71
Usage example:
72

73
```python
74
from rinohtype.structure import Section, Heading
75
from rinohtype.paragraph import Paragraph
76

77
# Create nested sections with headings
78
intro_heading = Heading("Introduction")
79
intro_content = Paragraph("This introduces the topic...")
80
intro_section = Section([intro_heading, intro_content], id='intro')
81

82
methods_heading = Heading("Methods")  
83
methods_content = Paragraph("The methodology used...")
84
methods_section = Section([methods_heading, methods_content], id='methods')
85

86
# Nested subsection
87
analysis_heading = Heading("Data Analysis")
88
analysis_content = Paragraph("Statistical analysis was performed...")
89
analysis_section = Section([analysis_heading, analysis_content], id='analysis')
90

91
# Add subsection to methods
92
methods_section.append(analysis_section)
93
```
94

95
### Lists
96

97
Ordered and unordered lists with customizable markers, nesting, and item formatting.
98

99
```python { .api }
100
class List(GroupedLabeledFlowables):
101
    """
102
    Ordered or unordered list container.
103
    
104
    Parameters:
105
    - list_items: list of ListItem objects
106
    - ordered: bool, whether list is numbered (True) or bulleted (False)
107
    - start: int, starting number for ordered lists
108
    - id: str, unique identifier
109
    - style: ListStyle object for list appearance
110
    - parent: parent element
111
    - source: source location information
112
    """
113
    def __init__(self, list_items, ordered=False, start=1, id=None, style=None, parent=None, source=None): ...
114

115
class ListItem(LabeledFlowable):
116
    """
117
    Individual list item with label and content.
118
    
119
    Parameters:
120
    - flowables: list of Flowable objects in the item
121
    - id: str, unique identifier
122
    - style: Style object for item formatting
123
    - parent: parent List element
124
    - source: source location information
125
    """
126
    def __init__(self, flowables, id=None, style=None, parent=None, source=None): ...
127

128
class ListItemLabel(Label):
129
    """Label for list items (bullet or number)."""
130

131
class ListStyle(Style):
132
    """Style configuration for lists including spacing, markers, and indentation."""
133
```
134

135
Usage example:
136

137
```python
138
from rinohtype.structure import List, ListItem
139
from rinohtype.paragraph import Paragraph
140

141
# Create bulleted list
142
items = [
143
    ListItem([Paragraph("First item")]),
144
    ListItem([Paragraph("Second item")]),  
145
    ListItem([Paragraph("Third item")])
146
]
147
bullet_list = List(items, ordered=False)
148

149
# Create numbered list
150
numbered_items = [
151
    ListItem([Paragraph("Step one: Prepare materials")]),
152
    ListItem([Paragraph("Step two: Begin process")]),
153
    ListItem([Paragraph("Step three: Complete task")])
154
]
155
numbered_list = List(numbered_items, ordered=True, start=1)
156

157
# Nested list
158
nested_item = ListItem([
159
    Paragraph("Main item"),
160
    List([
161
        ListItem([Paragraph("Sub-item A")]),
162
        ListItem([Paragraph("Sub-item B")])
163
    ], ordered=False)
164
])
165
```
166

167
### Definition Lists
168

169
Definition lists for glossaries, terminology, and key-value content presentation.
170

171
```python { .api }
172
class DefinitionList(GroupedLabeledFlowables):
173
    """
174
    Definition list containing term-definition pairs.
175
    
176
    Parameters:
177
    - items: list of (term, definition) tuples
178
    - id: str, unique identifier
179
    - style: Style object for list formatting
180
    - parent: parent element
181
    - source: source location information
182
    """
183
    def __init__(self, items, id=None, style=None, parent=None, source=None): ...
184
```
185

186
Usage example:
187

188
```python
189
from rinohtype.structure import DefinitionList
190
from rinohtype.paragraph import Paragraph
191

192
# Create definition list
193
definitions = [
194
    ("API", Paragraph("Application Programming Interface")),
195
    ("SDK", Paragraph("Software Development Kit")),
196
    ("IDE", Paragraph("Integrated Development Environment"))
197
]
198

199
def_list = DefinitionList(definitions)
200
```
201

202
### Tables
203

204
Comprehensive table system with headers, footers, spanning cells, and flexible formatting.
205

206
```python { .api }
207
class Table(Flowable):
208
    """
209
    Table with rows, columns, headers, and formatting options.
210
    
211
    Parameters:
212
    - body: TableBody containing table rows
213
    - head: TableHead, optional header section
214
    - align: HorizontalAlignment, table alignment
215
    - width: Dimension, explicit table width
216
    - column_widths: list of Dimension, column width specifications
217
    - id: str, unique identifier
218
    - style: TableStyle object for table appearance
219
    - parent: parent element
220
    """
221
    def __init__(self, body, head=None, align=None, width=None, column_widths=None, id=None, style=None, parent=None): ...
222

223
class TableSection(StaticGroupedFlowables):
224
    """
225
    Base class for table sections (head, body).
226
    
227
    Provides common functionality for organizing table rows into
228
    logical sections with consistent formatting and behavior.
229
    """
230

231
class TableHead(TableSection):
232
    """Table header section containing header rows."""
233

234
class TableBody(TableSection):
235
    """Table body section containing data rows."""
236

237
class TableRow(Styled):
238
    """
239
    Table row containing cells.
240
    
241
    Parameters:
242
    - cells: list of TableCell objects
243
    - id: str, unique identifier
244
    - style: Style object for row formatting
245
    - parent: parent TableSection
246
    - source: source location information
247
    """
248
    def __init__(self, cells, id=None, style=None, parent=None, source=None): ...
249

250
class TableCell(StaticGroupedFlowables):
251
    """
252
    Individual table cell with content and formatting.
253
    
254
    Parameters:
255
    - flowables: list of Flowable objects in the cell
256
    - rowspan: int, number of rows to span (default 1)
257
    - colspan: int, number of columns to span (default 1)
258
    - id: str, unique identifier
259
    - style: TableCellStyle object for cell appearance
260
    - parent: parent TableRow
261
    - source: source location information
262
    """
263
    def __init__(self, flowables, rowspan=1, colspan=1, id=None, style=None, parent=None, source=None): ...
264

265
class TableWithCaption(Float):
266
    """Table with caption as a figure."""
267
```
268

269
Usage example:
270

271
```python
272
from rinohtype.structure import Table, TableHead, TableBody, TableRow, TableCell
273
from rinohtype.paragraph import Paragraph
274

275
# Create table cells
276
header_cells = [
277
    TableCell([Paragraph("Name")]),
278
    TableCell([Paragraph("Age")]),
279
    TableCell([Paragraph("City")])
280
]
281

282
data_row1 = [
283
    TableCell([Paragraph("John Doe")]),
284
    TableCell([Paragraph("30")]),
285
    TableCell([Paragraph("New York")])
286
]
287

288
data_row2 = [
289
    TableCell([Paragraph("Jane Smith")]),
290
    TableCell([Paragraph("25")]),
291
    TableCell([Paragraph("Boston")])
292
]
293

294
# Build table structure
295
header = TableHead([TableRow(header_cells)])
296
body = TableBody([
297
    TableRow(data_row1),
298
    TableRow(data_row2)
299
])
300

301
table = Table(body, head=header)
302
```
303

304
### Headers and Footers
305

306
Page headers and footers with dynamic content and flexible positioning.
307

308
```python { .api }
309
class Header(GroupedFlowables):
310
    """
311
    Page header containing flowables for top-of-page content.
312
    
313
    Parameters:
314
    - flowables: list of Flowable objects for header content
315
    - id: str, unique identifier
316
    - style: Style object for header formatting
317
    - parent: parent element
318
    - source: source location information
319
    """
320
    def __init__(self, flowables, id=None, style=None, parent=None, source=None): ...
321

322
class Footer(GroupedFlowables):
323
    """
324
    Page footer containing flowables for bottom-of-page content.
325
    
326
    Parameters:
327
    - flowables: list of Flowable objects for footer content
328
    - id: str, unique identifier
329
    - style: Style object for footer formatting
330
    - parent: parent element
331
    - source: source location information
332
    """
333
    def __init__(self, flowables, id=None, style=None, parent=None, source=None): ...
334
```
335

336
### Horizontal Rules
337

338
Horizontal separator lines for visual content division.
339

340
```python { .api }
341
class HorizontalRule(Flowable):
342
    """
343
    Horizontal line separator.
344
    
345
    Parameters:
346
    - id: str, unique identifier
347
    - style: HorizontalRuleStyle object for line appearance
348
    - parent: parent element
349
    - source: source location information
350
    """
351
    def __init__(self, id=None, style=None, parent=None, source=None): ...
352

353
class HorizontalRuleStyle(Style):
354
    """Style configuration for horizontal rules including thickness, color, and spacing."""
355
```
356

357
### Admonitions
358

359
Special callout blocks for notes, warnings, tips, and other highlighted content.
360

361
```python { .api }
362
class Admonition(StaticGroupedFlowables):
363
    """
364
    Callout block for special content (note, warning, tip, etc.).
365
    
366
    Parameters:
367
    - flowables: list of Flowable objects in the admonition
368
    - type: str, admonition type ('note', 'warning', 'tip', etc.)
369
    - title: str, optional custom title
370
    - id: str, unique identifier
371
    - style: AdmonitionStyle object for appearance
372
    - parent: parent element
373
    - source: source location information
374
    """
375
    def __init__(self, flowables, type='note', title=None, id=None, style=None, parent=None, source=None): ...
376

377
class AdmonitionStyle(Style):
378
    """Style configuration for admonitions including borders, backgrounds, and typography."""
379

380
class AdmonitionTitleParagraph(Paragraph):
381
    """Special paragraph for admonition titles.""" 
382
```
383

384
Usage example:
385

386
```python
387
from rinohtype.structure import Admonition
388
from rinohtype.paragraph import Paragraph
389

390
# Create warning admonition
391
warning = Admonition([
392
    Paragraph("Be careful when modifying system files.")
393
], type='warning', title='Important Warning')
394

395
# Create note admonition
396
note = Admonition([
397
    Paragraph("This feature requires Python 3.8 or later.")
398
], type='note')
399
```