0
# Document Management
1

2
Core document creation, compilation, and structure management including sections, packages, and document-wide settings. The Document class serves as the top-level container for all LaTeX content and manages the document lifecycle from creation to PDF compilation.
3

4
## Capabilities
5

6
### Document Creation
7

8
The Document class represents a complete LaTeX document with preamble, packages, and content sections.
9

10
```python { .api }
11
class Document(Environment):
12
    def __init__(self, default_filepath="default_filepath", *, 
13
                 documentclass="article", document_options=None, 
14
                 fontenc="T1", inputenc="utf8", font_size="normalsize", 
15
                 lmodern=True, textcomp=True, microtype=None, 
16
                 page_numbers=True, indent=None, geometry_options=None, 
17
                 data=None):
18
        """
19
        Create a new LaTeX document.
20
        
21
        Parameters:
22
        - default_filepath: str, default file path for output
23
        - documentclass: str, LaTeX document class ('article', 'report', 'book', etc.)
24
        - document_options: list, options for document class
25
        - fontenc: str, font encoding (default 'T1')
26
        - inputenc: str, input encoding (default 'utf8')  
27
        - font_size: str, default font size
28
        - lmodern: bool, use Latin Modern fonts
29
        - textcomp: bool, enable text companion fonts
30
        - microtype: bool | None, enable microtypography (None uses config default)
31
        - page_numbers: bool, include page numbers
32
        - indent: bool, enable paragraph indentation
33
        - geometry_options: list, page geometry options
34
        - data: initial content for document
35
        """
36
```
37

38
Usage example:
39

40
```python
41
from pylatex import Document, Package
42

43
# Basic document
44
doc = Document('my_document', documentclass='article')
45

46
# Document with custom options
47
doc = Document(
48
    'technical_report',
49
    documentclass='report',
50
    document_options=['12pt', 'a4paper'],
51
    geometry_options=['margin=1in'],
52
    font_size='large'
53
)
54
```
55

56
### File Generation
57

58
Generate LaTeX source files and compile to PDF with various compilation options.
59

60
```python { .api }
61
def generate_tex(self, filepath=None):
62
    """
63
    Generate LaTeX source file.
64
    
65
    Parameters:
66
    - filepath: str, output file path (optional, uses default_filepath if None)
67
    """
68

69
def generate_pdf(self, filepath=None, *, clean=True, clean_tex=True, 
70
                 compiler=None, compiler_args=None, silent=True):
71
    """
72
    Compile document to PDF.
73
    
74
    Parameters:
75
    - filepath: str, output file path
76
    - clean: bool, remove auxiliary files after compilation
77
    - clean_tex: bool, remove .tex file after compilation
78
    - compiler: str, LaTeX compiler ('pdflatex', 'xelatex', 'lualatex')
79
    - compiler_args: list, additional compiler arguments
80
    - silent: bool, suppress compiler output
81
    
82
    Returns:
83
    - str: path to generated PDF file
84
    """
85
```
86

87
### Document Customization
88

89
Modify document properties, add colors, and set LaTeX variables.
90

91
```python { .api }
92
def add_color(self, name, model, description):
93
    """
94
    Add color definition to document.
95
    
96
    Parameters:
97
    - name: str, color name
98
    - model: str, color model ('rgb', 'cmyk', 'gray')
99
    - description: str, color specification
100
    """
101

102
def set_variable(self, name, value):
103
    """
104
    Set LaTeX variable in document.
105
    
106
    Parameters:
107
    - name: str, variable name
108
    - value: str, variable value
109
    """
110

111
def change_length(self, parameter, value):
112
    """
113
    Change LaTeX length parameter.
114
    
115
    Parameters:
116
    - parameter: str, length parameter name
117
    - value: str, new length value
118
    """
119

120
def change_page_style(self, style):
121
    """
122
    Change page style.
123
    
124
    Parameters:
125
    - style: str, page style name
126
    """
127

128
def change_document_style(self, style):
129
    """
130
    Change document style.
131
    
132
    Parameters:
133
    - style: str, document style name
134
    """
135
```
136

137
Usage example:
138

139
```python
140
from pylatex import Document
141

142
doc = Document()
143

144
# Add custom color
145
doc.add_color('myblue', 'RGB', '0,0,255')
146

147
# Set document variables
148
doc.set_variable('title', 'My Document Title')
149
doc.set_variable('author', 'John Doe')
150

151
# Modify page layout
152
doc.change_length('parindent', '0pt')
153
doc.change_page_style('fancy')
154
```
155

156
### Package Management
157

158
The Document class provides access to package management through the `packages` attribute.
159

160
```python { .api }
161
class Package(CommandBase):
162
    def __init__(self, name, options=None):
163
        """
164
        LaTeX package declaration.
165
        
166
        Parameters:
167
        - name: str, package name
168
        - options: list or str, package options
169
        """
170
```
171

172
Usage example:
173

174
```python
175
from pylatex import Document, Package
176

177
doc = Document()
178

179
# Add packages
180
doc.packages.append(Package('amsmath'))
181
doc.packages.append(Package('geometry', options=['margin=1in']))
182
doc.packages.append(Package('xcolor', options=['dvipsnames']))
183

184
# Packages are automatically added when using certain classes
185
from pylatex.math import Matrix
186
matrix = Matrix([[1, 2], [3, 4]])  # Automatically adds 'amsmath' package
187
doc.append(matrix)
188
```
189

190
## Document Properties
191

192
### Accessible Attributes
193

194
```python { .api }
195
# Document content areas
196
doc.packages     # Package list
197
doc.preamble     # Preamble content
198
doc.variables    # Document variables
199

200
# Document metadata
201
doc.default_filepath    # Default output path
202
doc.documentclass      # Document class
203
```
204

205
### Content Management
206

207
Documents act as containers and support all container operations:
208

209
```python
210
from pylatex import Document, Section
211

212
doc = Document()
213

214
# Add content directly
215
doc.append('Some text')
216

217
# Create structured content
218
with doc.create(Section('Introduction')) as section:
219
    section.append('This is the introduction.')
220
    
221
# Append existing objects
222
section = Section('Methods')
223
section.append('This is the methods section.')
224
doc.append(section)
225
```
226

227
## Compilation Requirements
228

229
PDF compilation requires a LaTeX distribution to be installed on the system:
230

231
- **Windows**: MiKTeX or TeX Live
232
- **macOS**: MacTeX or TeX Live
233
- **Linux**: TeX Live (usually available in package managers)
234

235
The default compiler is `pdflatex`, but you can specify alternatives:
236

237
```python
238
doc.generate_pdf(compiler='xelatex')  # For better Unicode support
239
doc.generate_pdf(compiler='lualatex')  # For advanced typography features
240
```