0
# Main Configuration
1
2
The main configuration system for pydoc-markdown, providing the core orchestration class and configuration loading capabilities.
3
4
## Capabilities
5
6
### PydocMarkdown Class
7
8
Main configuration class that orchestrates the entire documentation generation pipeline by managing loaders, processors, and renderers.
9
10
```python { .api }
11
class PydocMarkdown:
12
"""
13
Main configuration for Pydoc-Markdown.
14
15
Attributes:
16
loaders: List of loader implementations that load docspec.Modules (defaults to PythonLoader)
17
processors: List of processor implementations that modify docspec.Modules
18
(defaults to FilterProcessor, SmartProcessor, CrossrefProcessor)
19
renderer: Renderer for docspec.Modules (defaults to MarkdownRenderer)
20
hooks: Hooks for executing commands at certain points in the pipeline
21
unknown_fields: List of unknown configuration fields (filled automatically)
22
"""
23
loaders: List[Loader]
24
processors: List[Processor]
25
renderer: Renderer
26
hooks: Hooks
27
unknown_fields: List[str]
28
29
def load_config(self, arg: Union[str, dict]) -> None:
30
"""
31
Load configuration from nested data structure or filename.
32
33
Args:
34
arg: Configuration dictionary or path to config file (JSON, YAML, or TOML)
35
For pyproject.toml, reads from [tool.pydoc-markdown] section
36
"""
37
38
def init(self, context: Context) -> None:
39
"""
40
Initialize all plugins with specified context.
41
42
Args:
43
context: Context containing directory and other initialization data
44
45
Raises:
46
RuntimeError: If already initialized
47
"""
48
49
def load_modules(self) -> List[docspec.Module]:
50
"""
51
Load modules via the configured loaders.
52
53
Returns:
54
List of docspec.Module objects containing parsed API information
55
"""
56
57
def process(self, modules: List[docspec.Module]) -> None:
58
"""
59
Process modules via the configured processors.
60
61
Args:
62
modules: List of modules to process
63
"""
64
65
def render(self, modules: List[docspec.Module], run_hooks: bool = True) -> None:
66
"""
67
Render modules via the configured renderer.
68
69
Args:
70
modules: List of modules to render
71
run_hooks: Whether to run pre/post render hooks
72
"""
73
74
def build(self, site_dir: str) -> None:
75
"""
76
Build final output (only for renderers that support building).
77
78
Args:
79
site_dir: Directory for build output
80
81
Raises:
82
NotImplementedError: If renderer doesn't support building
83
"""
84
85
def run_hooks(self, hook_name: str) -> None:
86
"""
87
Execute hooks by name.
88
89
Args:
90
hook_name: Name of hook to run ("pre-render" or "post-render")
91
"""
92
```
93
94
### Hooks Configuration
95
96
Configuration for pre and post-render hooks that execute shell commands at specific points in the pipeline.
97
98
```python { .api }
99
class Hooks:
100
"""
101
Hook configuration for executing commands during rendering.
102
103
Attributes:
104
pre_render: List of shell commands to execute before rendering
105
post_render: List of shell commands to execute after rendering
106
"""
107
pre_render: List[str]
108
post_render: List[str]
109
```
110
111
## Usage Examples
112
113
### Basic Configuration
114
115
```python
116
from pydoc_markdown import PydocMarkdown
117
from pydoc_markdown.contrib.loaders.python import PythonLoader
118
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
119
120
# Create basic configuration
121
config = PydocMarkdown(
122
loaders=[PythonLoader(modules=['mypackage'])],
123
renderer=MarkdownRenderer(filename='docs/api.md')
124
)
125
126
# Generate documentation
127
modules = config.load_modules()
128
config.process(modules)
129
config.render(modules)
130
```
131
132
### Configuration from File
133
134
```python
135
from pydoc_markdown import PydocMarkdown
136
137
# Load from YAML file
138
config = PydocMarkdown()
139
config.load_config('pydoc-markdown.yml')
140
141
# Process documentation
142
modules = config.load_modules()
143
config.process(modules)
144
config.render(modules)
145
```
146
147
### Configuration with Hooks
148
149
```python
150
from pydoc_markdown import PydocMarkdown, Hooks
151
152
# Configuration with pre/post render hooks
153
config = PydocMarkdown(
154
hooks=Hooks(
155
pre_render=['echo "Starting documentation generation"'],
156
post_render=['echo "Documentation complete"', 'cp -r docs/ /var/www/']
157
)
158
)
159
160
config.load_config('pydoc-markdown.yml')
161
modules = config.load_modules()
162
config.process(modules)
163
config.render(modules) # Hooks will run automatically
164
```
165
166
### Manual Initialization
167
168
```python
169
from pydoc_markdown import PydocMarkdown
170
from pydoc_markdown.interfaces import Context
171
172
config = PydocMarkdown()
173
config.load_config('pydoc-markdown.yml')
174
175
# Manual initialization with custom context
176
context = Context(directory='/path/to/project')
177
config.init(context)
178
179
modules = config.load_modules()
180
config.process(modules)
181
config.render(modules)
182
```
183
184
## Configuration File Formats
185
186
### YAML Configuration
187
188
```yaml
189
loaders:
190
- type: python
191
modules: [mypackage]
192
search_path: [src/]
193
194
processors:
195
- type: filter
196
documented_only: true
197
- type: smart
198
- type: crossref
199
200
renderer:
201
type: mkdocs
202
config_file_path: mkdocs.yml
203
build_directory: site/
204
205
hooks:
206
pre-render:
207
- echo "Starting build"
208
post-render:
209
- echo "Build complete"
210
```
211
212
### TOML Configuration (pyproject.toml)
213
214
```toml
215
[tool.pydoc-markdown]
216
217
[[tool.pydoc-markdown.loaders]]
218
type = "python"
219
modules = ["mypackage"]
220
search_path = ["src/"]
221
222
[[tool.pydoc-markdown.processors]]
223
type = "filter"
224
documented_only = true
225
226
[[tool.pydoc-markdown.processors]]
227
type = "smart"
228
229
[[tool.pydoc-markdown.processors]]
230
type = "crossref"
231
232
[tool.pydoc-markdown.renderer]
233
type = "mkdocs"
234
config_file_path = "mkdocs.yml"
235
build_directory = "site/"
236
```