0
# Pydoc-Markdown
1

2
An extensible framework for generating Python API documentation in Markdown format. Pydoc-markdown parses Python source code using docspec (without executing it), processes docstrings through configurable processors, and renders comprehensive documentation through various output formats including standalone Markdown, MkDocs, Hugo, and Docusaurus.
3

4
## Package Information
5

6
- **Package Name**: pydoc-markdown
7
- **Language**: Python
8
- **Installation**: `pip install pydoc-markdown`
9
- **Requirements**: Python 3.7+
10

11
## Core Imports
12

13
```python
14
from pydoc_markdown import PydocMarkdown
15
```
16

17
Common imports for customization:
18

19
```python
20
from pydoc_markdown.contrib.loaders.python import PythonLoader
21
from pydoc_markdown.contrib.processors.filter import FilterProcessor
22
from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor
23
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
24
from pydoc_markdown.contrib.renderers.mkdocs import MkdocsRenderer
25
```
26

27
## Basic Usage
28

29
### CLI Usage
30

31
```bash
32
# Generate docs with default configuration
33
pydoc-markdown
34

35
# Generate docs for specific modules
36
pydoc-markdown -m mypackage.module1 -m mypackage.module2
37

38
# Generate docs for entire packages
39
pydoc-markdown -p mypackage
40

41
# Start development server (for MkDocs renderer)
42
pydoc-markdown --server
43

44
# Bootstrap configuration files
45
pydoc-markdown --bootstrap mkdocs
46
```
47

48
### Programmatic Usage
49

50
```python
51
from pydoc_markdown import PydocMarkdown
52
from pydoc_markdown.contrib.loaders.python import PythonLoader
53
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
54

55
# Create configuration
56
config = PydocMarkdown(
57
    loaders=[PythonLoader(modules=['mypackage'])],
58
    renderer=MarkdownRenderer(filename='api.md')
59
)
60

61
# Generate documentation
62
modules = config.load_modules()
63
config.process(modules)
64
config.render(modules)
65
```
66

67
### Configuration File Usage
68

69
Create `pydoc-markdown.yml`:
70

71
```yaml
72
loaders:
73
  - type: python
74
    modules: [mypackage]
75
processors:
76
  - type: filter
77
  - type: smart
78
  - type: crossref
79
renderer:
80
  type: markdown
81
  filename: api.md
82
```
83

84
Then run: `pydoc-markdown`
85

86
## Architecture
87

88
Pydoc-markdown uses a plugin-based architecture with three main component types:
89

90
- **Loaders**: Extract API information from source code (Python, etc.)
91
- **Processors**: Transform and enhance docstrings (Google/Sphinx style, cross-references, filtering)
92
- **Renderers**: Generate output in various formats (Markdown, MkDocs, Hugo, Docusaurus)
93

94
The framework processes documentation in stages:
95
1. **Load**: Parse source code into docspec.Module objects
96
2. **Process**: Transform docstrings and apply filters
97
3. **Render**: Generate final documentation output
98

99
This modular design enables flexible documentation workflows, from simple single-file generation to complex multi-format publishing pipelines integrated with static site generators.
100

101
## Capabilities
102

103
### Main Configuration
104

105
Core configuration class for orchestrating the documentation generation pipeline, managing loaders, processors, and renderers.
106

107
```python { .api }
108
class PydocMarkdown:
109
    loaders: List[Loader]
110
    processors: List[Processor]  
111
    renderer: Renderer
112
    hooks: Hooks
113
    
114
    def load_config(self, arg: Union[str, dict]) -> None: ...
115
    def load_modules(self) -> List[docspec.Module]: ...
116
    def process(self, modules: List[docspec.Module]) -> None: ...
117
    def render(self, modules: List[docspec.Module], run_hooks: bool = True) -> None: ...
118
    def build(self, site_dir: str) -> None: ...
119
```
120

121
[Main Configuration](./main-config.md)
122

123
### Python Source Loading
124

125
Load and parse Python source code into docspec objects for documentation generation, with support for module discovery, package analysis, and various parsing options.
126

127
```python { .api }
128
class PythonLoader(Loader):
129
    modules: List[str]
130
    packages: List[str]
131
    search_path: List[str]
132
    ignore_when_discovered: List[str]
133
    parser: docspec_python.Parser
134
    
135
    def load(self) -> Iterable[docspec.Module]: ...
136
```
137

138
[Python Loading](./python-loading.md)
139

140
### Docstring Processing
141

142
Transform and enhance docstrings through configurable processors including filtering, smart formatting, cross-reference resolution, and conversion from various documentation styles.
143

144
```python { .api }
145
class FilterProcessor(Processor):
146
    expression: Optional[str]
147
    documented_only: bool
148
    do_not_filter_modules: bool
149
    skip_empty_modules: bool
150
    
151
class CrossrefProcessor(Processor):
152
    loader: Optional[str]
153
    safe_mode: bool
154
    
155
class GoogleProcessor(Processor): ...
156
class SphinxProcessor(Processor): ...
157
class SmartProcessor(Processor): ...
158
class PydocmdProcessor(Processor): ...
159
```
160

161
[Docstring Processing](./docstring-processing.md)
162

163
### Documentation Rendering
164

165
Generate documentation output in various formats including standalone Markdown, MkDocs, Hugo, Docusaurus, and custom Jinja2 templates.
166

167
```python { .api }
168
class MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer):
169
    filename: Optional[str]
170
    render_toc: bool
171
    insert_header_anchors: bool
172
    code_lang: str
173
    
174
class MkdocsRenderer(Renderer, Server, Builder):
175
    config_file_path: str
176
    build_directory: str
177
    site_dir: str
178
    
179
class HugoRenderer(Renderer, Server, Builder):
180
    config_file: str
181
    build_directory: str
182
    site_dir: str
183
    hugo_cmd: str
184
```
185

186
[Documentation Rendering](./documentation-rendering.md)
187

188
### CLI Interface
189

190
Command-line interface providing comprehensive options for documentation generation, development servers, and project bootstrapping.
191

192
```python { .api }
193
class RenderSession:
194
    def __init__(
195
        self,
196
        config: Union[None, dict, str],
197
        render_toc: Optional[bool] = None,
198
        search_path: Optional[List[str]] = None,
199
        modules: Optional[List[str]] = None,
200
        packages: Optional[List[str]] = None,
201
        py2: Optional[bool] = None
202
    ): ...
203
    
204
    def load(self) -> PydocMarkdown: ...
205
    def render(self, config: PydocMarkdown) -> List[str]: ...
206
    def build(self, config: PydocMarkdown, site_dir: str) -> None: ...
207
    def run_server(self, config: PydocMarkdown, open_browser: bool = False): ...
208

209
def cli() -> None: ...
210
```
211

212
[CLI Interface](./cli-interface.md)
213

214
### Plugin Interfaces
215

216
Abstract interfaces defining the plugin architecture for loaders, processors, renderers, and additional functionality like source linking and development servers.
217

218
```python { .api }
219
class Context:
220
    directory: str
221

222
class Loader(PluginBase):
223
    def load(self) -> Iterable[docspec.Module]: ...
224

225
class Processor(PluginBase):
226
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None: ...
227

228
class Renderer(PluginBase):
229
    def render(self, modules: List[docspec.Module]) -> None: ...
230
    def get_resolver(self, modules: List[docspec.Module]) -> Optional[Resolver]: ...
231

232
class SourceLinker(PluginBase):
233
    def get_source_url(self, obj: docspec.ApiObject) -> Optional[str]: ...
234
```
235

236
[Plugin Interfaces](./plugin-interfaces.md)
237

238
### Utility Functions
239

240
Helper functions and classes for common operations including docspec manipulation, template processing, file watching, and page management.
241

242
```python { .api }
243
def get_members_of_type(objs: Union[docspec.ApiObject, List[docspec.ApiObject]], type_: Type[T]) -> List[T]: ...
244
def format_function_signature(func: docspec.Function, exclude_self: bool = False) -> str: ...
245
def is_function(obj: docspec.ApiObject) -> TypeGuard[docspec.Function]: ...
246
def is_method(obj: docspec.ApiObject) -> TypeGuard[docspec.Function]: ...
247
def watch_paths(paths: List[str]) -> Tuple[Observer, Event]: ...
248

249
class Attributor:
250
    def __init__(self, data: Dict[str, Any]): ...
251
    def __getattr__(self, name: str) -> Any: ...
252
```
253

254
[Utility Functions](./utility-functions.md)
255

256
## Types
257

258
```python { .api }
259
class Hooks:
260
    pre_render: List[str]
261
    post_render: List[str]
262

263
class LoaderError(Exception): ...
264

265
class Resolver(ABC):
266
    def resolve_ref(self, scope: docspec.ApiObject, ref: str) -> Optional[str]: ...
267

268
class ResolverV2(ABC):
269
    def resolve_reference(self, suite: ApiSuite, scope: docspec.ApiObject, ref: str) -> Optional[docspec.ApiObject]: ...
270

271
class SinglePageRenderer(PluginBase):
272
    def render_single_page(self, fp: TextIO, modules: List[docspec.Module], page_title: Optional[str] = None) -> None: ...
273

274
class SingleObjectRenderer(PluginBase):
275
    def render_object(self, fp: TextIO, obj: docspec.ApiObject, options: Dict[str, Any]) -> None: ...
276

277
class Server(ABC):
278
    def get_server_url(self) -> str: ...
279
    def start_server(self) -> subprocess.Popen: ...
280
    def reload_server(self, process: subprocess.Popen) -> subprocess.Popen: ...
281

282
class Builder(ABC):
283
    def build(self, site_dir: str) -> None: ...
284
```