0
# Documentation Objects
1
2
Object model for representing Python modules, classes, functions, and variables with their metadata, signatures, and docstrings. These objects form the core data structure that pdoc uses to represent Python code for documentation generation.
3
4
## Capabilities
5
6
### Base Documentation Object
7
8
Foundation class for all documentation objects, providing common attributes and methods for Python constructs.
9
10
```python { .api }
11
class Doc:
12
"""
13
Base documentation object for all Python constructs.
14
15
Attributes:
16
- name: str - Simple name of the object
17
- qualname: str - Qualified name within module
18
- fullname: str - Full dotted name including module
19
- obj: Any - The actual Python object being documented
20
- taken_from: tuple[str, str] - Module and qualname where defined
21
"""
22
name: str
23
qualname: str
24
fullname: str
25
obj: Any
26
taken_from: tuple[str, str]
27
```
28
29
### Namespace Objects
30
31
Base class for containers that hold other documentation objects (modules and classes).
32
33
```python { .api }
34
class Namespace(Doc):
35
"""
36
Base class for modules and classes that contain other objects.
37
38
Attributes:
39
- members: dict[str, Doc] - Dictionary of contained documentation objects
40
"""
41
members: dict[str, Doc]
42
```
43
44
### Module Documentation
45
46
Represents Python modules with their contained classes, functions, and variables.
47
48
```python { .api }
49
class Module(Namespace):
50
"""
51
Module documentation object representing a Python module.
52
53
Methods:
54
- from_name(module_name): Create Module from module name string
55
"""
56
57
@classmethod
58
def from_name(cls, module_name: str) -> 'Module':
59
"""
60
Create Module object from module name.
61
62
Parameters:
63
- module_name: str - Dotted module name or file path
64
65
Returns:
66
- Module: Documentation object for the module
67
68
Raises:
69
- ImportError: If module cannot be loaded
70
"""
71
```
72
73
### Class Documentation
74
75
Represents Python classes with their methods, properties, and attributes.
76
77
```python { .api }
78
class Class(Namespace):
79
"""
80
Class documentation object representing a Python class.
81
82
Inherits all Namespace functionality for containing methods and attributes.
83
"""
84
pass
85
```
86
87
### Function Documentation
88
89
Represents Python functions and methods with their signatures and docstrings.
90
91
```python { .api }
92
class Function(Doc):
93
"""
94
Function documentation object for functions and methods.
95
96
Captures function signatures, parameters, return types, and docstrings.
97
"""
98
pass
99
```
100
101
### Variable Documentation
102
103
Represents module-level variables, class attributes, and instance variables.
104
105
```python { .api }
106
class Variable(Doc):
107
"""
108
Variable documentation object for module variables and class attributes.
109
110
Handles type annotations and docstring extraction for variables.
111
"""
112
pass
113
```
114
115
## Usage Examples
116
117
### Creating Documentation Objects
118
119
```python
120
from pdoc.doc import Module, Class, Function
121
122
# Create module documentation from name
123
module_doc = Module.from_name("my_package.submodule")
124
125
# Access module contents
126
for name, obj in module_doc.members.items():
127
print(f"{name}: {type(obj).__name__}")
128
129
# Get specific class from module
130
if "MyClass" in module_doc.members:
131
class_doc = module_doc.members["MyClass"]
132
if isinstance(class_doc, Class):
133
# Access class methods
134
for method_name, method_obj in class_doc.members.items():
135
if isinstance(method_obj, Function):
136
print(f"Method: {method_name}")
137
```
138
139
### Working with Documentation Hierarchy
140
141
```python
142
from pdoc.doc import Module
143
144
# Load module with all submodules
145
main_module = Module.from_name("my_package")
146
147
def walk_docs(doc_obj, level=0):
148
"""Recursively walk documentation objects"""
149
indent = " " * level
150
print(f"{indent}{doc_obj.name} ({type(doc_obj).__name__})")
151
152
if hasattr(doc_obj, 'members'):
153
for member in doc_obj.members.values():
154
walk_docs(member, level + 1)
155
156
walk_docs(main_module)
157
```
158
159
### Accessing Object Metadata
160
161
```python
162
from pdoc.doc import Module, Function
163
164
module_doc = Module.from_name("math")
165
166
# Access documentation attributes
167
for name, member in module_doc.members.items():
168
print(f"Name: {member.name}")
169
print(f"Full name: {member.fullname}")
170
print(f"Qualified name: {member.qualname}")
171
print(f"Taken from: {member.taken_from}")
172
173
if isinstance(member, Function):
174
# Access the actual Python function object
175
actual_function = member.obj
176
print(f"Function signature: {actual_function.__annotations__}")
177
```
178
179
## Integration with Rendering
180
181
```python
182
from pdoc.doc import Module
183
from pdoc import render
184
185
# Create documentation objects
186
modules = {
187
"main": Module.from_name("my_package"),
188
"utils": Module.from_name("my_package.utils")
189
}
190
191
# Render individual module
192
html_output = render.html_module(modules["main"], modules)
193
194
# Generate index page
195
index_html = render.html_index(modules)
196
```