0
# Document Sectioning
1
2
Hierarchical document structure with chapters, sections, subsections, and automatic numbering and labeling. PyLaTeX provides a complete sectioning system that mirrors LaTeX's document structure commands.
3
4
## Capabilities
5
6
### Section Hierarchy
7
8
PyLaTeX provides the complete LaTeX sectioning hierarchy with automatic numbering and optional labeling.
9
10
```python { .api }
11
class Section(Container):
12
def __init__(self, title, numbering=None, *, label=True, **kwargs):
13
"""
14
Document section with automatic numbering and labeling.
15
16
Parameters:
17
- title: str, section title
18
- numbering: bool, enable/disable numbering (None uses default)
19
- label: bool or str, automatic label generation or custom label
20
"""
21
22
# Properties
23
marker_prefix = "sec" # Default label prefix
24
25
class Chapter(Section):
26
"""Chapter-level section (\\chapter)."""
27
marker_prefix = "chap"
28
29
class Subsection(Section):
30
"""Subsection (\\subsection)."""
31
marker_prefix = "subsec"
32
33
class Subsubsection(Section):
34
"""Sub-subsection (\\subsubsection)."""
35
marker_prefix = "ssubsec"
36
```
37
38
### Section Usage
39
40
Basic section creation with automatic numbering:
41
42
```python
43
from pylatex import Document, Chapter, Section, Subsection, Subsubsection
44
45
# For book or report document class
46
doc = Document(documentclass='report')
47
48
with doc.create(Chapter('Introduction')):
49
doc.append('This is the introduction chapter.')
50
51
with doc.create(Section('Background')):
52
doc.append('Background information.')
53
54
with doc.create(Subsection('Historical Context')):
55
doc.append('Historical background.')
56
57
with doc.create(Subsubsection('Ancient Period')):
58
doc.append('Ancient historical context.')
59
60
# For article document class (no chapters)
61
article = Document(documentclass='article')
62
63
with article.create(Section('Methods')):
64
article.append('Methodology description.')
65
66
with article.create(Subsection('Data Collection')):
67
article.append('How data was collected.')
68
```
69
70
### Numbering Control
71
72
Control section numbering behavior:
73
74
```python
75
from pylatex import Document, Section, Subsection
76
77
doc = Document()
78
79
# Numbered sections (default)
80
with doc.create(Section('Numbered Section')):
81
doc.append('This section is numbered.')
82
83
# Unnumbered sections
84
with doc.create(Section('Unnumbered Section', numbering=False)):
85
doc.append('This section is not numbered.')
86
87
# Mixed numbering
88
with doc.create(Section('Parent Section')):
89
with doc.create(Subsection('Numbered Subsection')):
90
doc.append('This subsection is numbered.')
91
92
with doc.create(Subsection('Unnumbered Subsection', numbering=False)):
93
doc.append('This subsection is not numbered.')
94
```
95
96
### Label Management
97
98
Automatic and manual label generation for cross-referencing:
99
100
```python
101
from pylatex import Document, Section, Ref
102
103
doc = Document()
104
105
# Automatic labeling (default)
106
with doc.create(Section('Methods')) as methods:
107
methods.append('This section has an automatic label.')
108
109
# Custom labels
110
with doc.create(Section('Results', label='custom-results')) as results:
111
results.append('This section has a custom label.')
112
113
# Disable labeling
114
with doc.create(Section('Discussion', label=False)) as discussion:
115
discussion.append('This section has no label.')
116
117
# Reference sections
118
doc.append('See ')
119
doc.append(Ref('sec:methods'))
120
doc.append(' for methodology details.')
121
```
122
123
## Section Patterns
124
125
### Nested Section Structure
126
127
Create complex document hierarchies:
128
129
```python
130
from pylatex import Document, Chapter, Section, Subsection
131
132
doc = Document(documentclass='book')
133
134
with doc.create(Chapter('Literature Review')):
135
with doc.create(Section('Theoretical Framework')):
136
with doc.create(Subsection('Core Concepts')):
137
doc.append('Fundamental concepts.')
138
139
with doc.create(Subsection('Related Work')):
140
doc.append('Previous research.')
141
142
with doc.create(Section('Research Gaps')):
143
doc.append('Identified gaps in literature.')
144
145
with doc.create(Chapter('Methodology')):
146
with doc.create(Section('Research Design')):
147
doc.append('Overall research approach.')
148
149
with doc.create(Section('Data Analysis')):
150
with doc.create(Subsection('Quantitative Methods')):
151
doc.append('Statistical analysis methods.')
152
153
with doc.create(Subsection('Qualitative Methods')):
154
doc.append('Qualitative analysis approach.')
155
```
156
157
### Section with Complex Content
158
159
Sections can contain any LaTeX content:
160
161
```python
162
from pylatex import Document, Section, Subsection
163
from pylatex import Figure, Table, Math
164
165
doc = Document()
166
167
with doc.create(Section('Analysis')) as analysis:
168
analysis.append('This section contains various content types.')
169
170
# Add figure
171
with analysis.create(Figure(position='h')) as fig:
172
fig.add_image('data_plot.png', width=NoEscape(r'0.8\\textwidth'))
173
fig.add_caption('Data visualization')
174
175
# Add subsection with math
176
with analysis.create(Subsection('Mathematical Model')):
177
with analysis.create(Math()) as math:
178
math.append(r'E = mc^2')
179
180
# Add table
181
with analysis.create(Subsection('Results Summary')):
182
# Table creation code here...
183
pass
184
```
185
186
### Document Class Considerations
187
188
Different document classes support different sectioning levels:
189
190
```python
191
# Article class hierarchy
192
article = Document(documentclass='article')
193
# Available: Section, Subsection, Subsubsection, Paragraph, Subparagraph
194
195
# Report class hierarchy
196
report = Document(documentclass='report')
197
# Available: Chapter, Section, Subsection, Subsubsection, Paragraph, Subparagraph
198
199
# Book class hierarchy
200
book = Document(documentclass='book')
201
# Available: Part, Chapter, Section, Subsection, Subsubsection, Paragraph, Subparagraph
202
```
203
204
### Custom Section Formatting
205
206
Customize section appearance and behavior:
207
208
```python
209
from pylatex import Document, Section, Command
210
211
doc = Document()
212
213
# Add custom section formatting to preamble
214
doc.preamble.append(Command('titleformat',
215
arguments=[NoEscape(r'\section'),
216
NoEscape(r'\Large\bfseries'),
217
NoEscape(r'\thesection'),
218
NoEscape(r'1em'),
219
NoEscape(r'{}')]))
220
221
# Use sections normally
222
with doc.create(Section('Custom Formatted Section')):
223
doc.append('This section uses custom formatting.')
224
```
225
226
## Advanced Section Features
227
228
### Table of Contents Integration
229
230
Sections automatically appear in table of contents:
231
232
```python
233
from pylatex import Document, Chapter, Section, Command
234
235
doc = Document(documentclass='report')
236
237
# Add table of contents
238
doc.append(Command('tableofcontents'))
239
doc.append(Command('newpage'))
240
241
# Create sections (automatically added to TOC)
242
with doc.create(Chapter('Introduction')):
243
doc.append('Introduction content.')
244
245
with doc.create(Chapter('Methods')):
246
with doc.create(Section('Data Collection')):
247
doc.append('Data collection methods.')
248
```
249
250
### Section Depth Control
251
252
Control how deep sections appear in TOC:
253
254
```python
255
from pylatex import Document, Command
256
257
doc = Document()
258
259
# Set TOC depth (0=chapter, 1=section, 2=subsection, etc.)
260
doc.preamble.append(Command('setcounter', arguments=['tocdepth', '2']))
261
262
# Set section numbering depth
263
doc.preamble.append(Command('setcounter', arguments=['secnumdepth', '3']))
264
```
265
266
### Cross-Referencing Sections
267
268
Use section labels for cross-references throughout the document:
269
270
```python
271
from pylatex import Document, Section, Ref, Pageref
272
273
doc = Document()
274
275
with doc.create(Section('Introduction', label='intro')):
276
doc.append('This is the introduction.')
277
278
with doc.create(Section('Methods', label='methods')):
279
doc.append('As discussed in ')
280
doc.append(Ref('intro'))
281
doc.append(', this research uses the following methods.')
282
283
# Page references
284
doc.append('See page ')
285
doc.append(Pageref('methods'))
286
doc.append(' for detailed methodology.')
287
```