demo_long
Test Module
This is a test module demonstrating pdoc's parsing capabilities.
- All docstrings support plain markdown.
Including code!
print("hello world")
You can link to classes or modules by putting them between backticks:
demo.Dog.bark
- The only requirement is that you must specify the full qualified path for external modules.
- Module members appear in the order they are listed in the source code. If you do not like the order in pdoc, you should probably have a different order in your source file as well.
A Second Section
You can have multiple sections in your module docstring, which will also show up in the navigation.
1""" 2 3# Test Module 4 5This is a test module demonstrating pdoc's parsing capabilities. 6 7- All docstrings support plain markdown. 8- Including code! 9 10 ```python 11 print("hello world") 12 ``` 13- You can link to classes or modules by putting them between backticks: `demo.Dog.bark` 14 - The only requirement is that you must specify the full qualified path for external modules. 15- Module members appear in the order they are listed in the source code. 16 If you do not like the order in pdoc, you should probably have a different order in your source file as well. 17 18# A Second Section 19 20You can have multiple sections in your module docstring, 21which will also show up in the navigation. 22""" 23 24from __future__ import annotations 25 26import abc 27from dataclasses import dataclass 28from dataclasses import field 29import enum 30from functools import cached_property 31import os 32from typing import ClassVar 33from typing import List 34from typing import Optional 35from typing import Sequence 36from typing import TypeVar 37from typing import Union 38 39from pdoc._compat import cache 40 41FOO_CONSTANT: int = 42 42""" 43A happy constant. ✨ 44pdoc documents constants with their type annotation and default value. 45""" 46 47FOO_SINGLETON: "Foo" 48""" 49This variable is annotated with a type only, but not assigned to a value. 50We also haven't defined the associated type (`Foo`) yet, 51so the type annotation in the code in the source code is actually a string literal: 52 53```python 54FOO_SINGLETON: "Foo" 55``` 56 57Similar to mypy, pdoc resolves 58[string forward references](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#class-name-forward-references) 59automatically. 60""" 61 62NO_DOCSTRING: int 63# this variable has a type annotation but not docstring. 64 65 66def a_simple_function(a: str) -> str: 67 """ 68 This is a basic module-level function. 69 70 For a more complex example, take a look at `a_complex_function`! 71 """ 72 return a.upper() 73 74 75T = TypeVar("T") 76 77 78def a_complex_function( 79 a: str, b: Union["Foo", str], *, c: Optional[T] = None 80) -> Optional[T]: 81 """ 82 This is a function with a fairly complex signature, 83 involving type annotations with `typing.Union`, a `typing.TypeVar` (~T), 84 as well as a keyword-only arguments (*). 85 """ 86 return None 87 88 89class Foo: 90 """ 91 `Foo` is a basic class without any parent classes (except for the implicit `object` class). 92 93 You will see in the definition of `Bar` that docstrings are inherited by default. 94 95 Functions in the current scope can be referenced without prefix: `a_regular_function()`. 96 """ 97 98 an_attribute: Union[str, List["int"]] 99 """A regular attribute with type annotations""" 100 101 a_class_attribute: ClassVar[str] = "lots of foo!" 102 """An attribute with a ClassVar annotation.""" 103 104 def __init__(self) -> None: 105 """ 106 The constructor is currently always listed first as this feels most natural.""" 107 self.a_constructor_only_attribute: int = 42 108 """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.""" 109 110 self.undocumented_constructor_attribute = 42 111 a_complex_function("a", "Foo") 112 113 def a_regular_function(self) -> "Foo": 114 """This is a regular method, returning the object itself.""" 115 return self 116 117 @property 118 def a_property(self) -> str: 119 """This is a `@property` attribute. pdoc will display it as a variable.""" 120 return "true foo" 121 122 @cached_property 123 def a_cached_property(self) -> str: 124 """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well.""" 125 return "true foo" 126 127 @cache 128 def a_cached_function(self) -> str: 129 """This is method with `@cache` decoration.""" 130 return "true foo" 131 132 @classmethod 133 def a_class_method(cls) -> int: 134 """This is what a `@classmethod` looks like.""" 135 return 24 136 137 @classmethod # type: ignore 138 @property 139 def a_class_property(cls) -> int: 140 """This is what a `@classmethod @property` looks like.""" 141 return 24 142 143 @staticmethod 144 def a_static_method(): 145 """This is what a `@staticmethod` looks like.""" 146 print("Hello World") 147 148 149class Bar(Foo): 150 bar: str 151 """A new attribute defined on this subclass.""" 152 153 class Baz: 154 """ 155 This class is an attribute of `Bar`. 156 To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation 157 (but not in the navigation). 158 159 It should be noted that inner classes are a pattern you most often want to avoid in Python. 160 Think about moving stuff in a new package instead! 161 162 This class has no __init__ method defined, so pdoc will not show a constructor. 163 """ 164 165 def wat(self): 166 """A regular method. Above, you see what happens if a class has no constructor defined and 167 no constructor docstring.""" 168 169 170async def i_am_async(self) -> int: 171 """ 172 This is an example of an async function. 173 174 - Knock, knock 175 - An async function 176 - Who's there? 177 """ 178 raise NotImplementedError 179 180 181@cache 182def fib(n): 183 """ 184 This is an example of decorated function. Decorators are included in the documentation as well. 185 This is often useful when documenting web APIs, for example. 186 """ 187 if n < 2: 188 return n 189 return fib(n - 1) + fib(n - 2) 190 191 192def security(test=os.environ): 193 """ 194 Default values are generally rendered using repr(), 195 but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data. 196 """ 197 return False 198 199 200class DoubleInherit(Foo, Bar.Baz, abc.ABC): 201 """This is an example of a class that inherits from multiple parent classes.""" 202 203 204CONST_B = "yes" 205"""A constant without type annotation""" 206 207CONST_NO_DOC = "SHOULD NOT APPEAR" 208 209 210@dataclass 211class DataDemo: 212 """ 213 This is an example for a dataclass. 214 215 As usual, you can link to individual properties: `DataDemo.a`. 216 """ 217 218 a: int 219 """Again, we can document individual properties with docstrings.""" 220 a2: Sequence[str] 221 # This property has a type annotation but is not documented. 222 a3 = "a3" 223 # This property has a default value but is not documented. 224 a4: str = "a4" 225 # This property has a type annotation and a default value but is not documented. 226 b: bool = field(repr=False, default=True) 227 """This property is assigned to `dataclasses.field()`, which works just as well.""" 228 229 230@dataclass 231class DataDemoExtended(DataDemo): 232 c: str = "42" 233 """A new attribute.""" 234 235 236class EnumDemo(enum.Enum): 237 """ 238 This is an example of an Enum. 239 240 As usual, you can link to individual properties: `GREEN`. 241 """ 242 243 RED = 1 244 """I am the red.""" 245 GREEN = 2 246 """I am green.""" 247 BLUE = enum.auto() 248 249 250def embed_image(): 251 """ 252 This docstring includes an embedded image: 253 254 ``` 255 ![pdoc logo](../docs/logo.png) 256 ``` 257 258 ![pdoc logo](../../docs/logo.png) 259 """ 260 261 262def admonitions(): 263 """ 264 pdoc also supports basic reStructuredText admonitions: 265 266 ``` 267 .. note/warning/danger:: Optional title 268 Body text 269 ``` 270 271 .. note:: 272 Hi there! 273 274 .. warning:: Be Careful! 275 This warning has both a title and content. 276 277 .. danger:: 278 Danger ahead. 279 280 """
A happy constant. ✨
pdoc documents constants with their type annotation and default value.
This variable is annotated with a type only, but not assigned to a value.
We also haven't defined the associated type (Foo
) yet,
so the type annotation in the code in the source code is actually a string literal:
FOO_SINGLETON: "Foo"
Similar to mypy, pdoc resolves string forward references automatically.
67def a_simple_function(a: str) -> str: 68 """ 69 This is a basic module-level function. 70 71 For a more complex example, take a look at `a_complex_function`! 72 """ 73 return a.upper()
This is a basic module-level function.
For a more complex example, take a look at a_complex_function
!
79def a_complex_function( 80 a: str, b: Union["Foo", str], *, c: Optional[T] = None 81) -> Optional[T]: 82 """ 83 This is a function with a fairly complex signature, 84 involving type annotations with `typing.Union`, a `typing.TypeVar` (~T), 85 as well as a keyword-only arguments (*). 86 """ 87 return None
This is a function with a fairly complex signature,
involving type annotations with typing.Union
, a typing.TypeVar
(~T),
as well as a keyword-only arguments (*).
90class Foo: 91 """ 92 `Foo` is a basic class without any parent classes (except for the implicit `object` class). 93 94 You will see in the definition of `Bar` that docstrings are inherited by default. 95 96 Functions in the current scope can be referenced without prefix: `a_regular_function()`. 97 """ 98 99 an_attribute: Union[str, List["int"]] 100 """A regular attribute with type annotations""" 101 102 a_class_attribute: ClassVar[str] = "lots of foo!" 103 """An attribute with a ClassVar annotation.""" 104 105 def __init__(self) -> None: 106 """ 107 The constructor is currently always listed first as this feels most natural.""" 108 self.a_constructor_only_attribute: int = 42 109 """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.""" 110 111 self.undocumented_constructor_attribute = 42 112 a_complex_function("a", "Foo") 113 114 def a_regular_function(self) -> "Foo": 115 """This is a regular method, returning the object itself.""" 116 return self 117 118 @property 119 def a_property(self) -> str: 120 """This is a `@property` attribute. pdoc will display it as a variable.""" 121 return "true foo" 122 123 @cached_property 124 def a_cached_property(self) -> str: 125 """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well.""" 126 return "true foo" 127 128 @cache 129 def a_cached_function(self) -> str: 130 """This is method with `@cache` decoration.""" 131 return "true foo" 132 133 @classmethod 134 def a_class_method(cls) -> int: 135 """This is what a `@classmethod` looks like.""" 136 return 24 137 138 @classmethod # type: ignore 139 @property 140 def a_class_property(cls) -> int: 141 """This is what a `@classmethod @property` looks like.""" 142 return 24 143 144 @staticmethod 145 def a_static_method(): 146 """This is what a `@staticmethod` looks like.""" 147 print("Hello World")
Foo
is a basic class without any parent classes (except for the implicit object
class).
You will see in the definition of Bar
that docstrings are inherited by default.
Functions in the current scope can be referenced without prefix: a_regular_function()
.
105 def __init__(self) -> None: 106 """ 107 The constructor is currently always listed first as this feels most natural.""" 108 self.a_constructor_only_attribute: int = 42 109 """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.""" 110 111 self.undocumented_constructor_attribute = 42 112 a_complex_function("a", "Foo")
The constructor is currently always listed first as this feels most natural.
This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.
114 def a_regular_function(self) -> "Foo": 115 """This is a regular method, returning the object itself.""" 116 return self
This is a regular method, returning the object itself.
118 @property 119 def a_property(self) -> str: 120 """This is a `@property` attribute. pdoc will display it as a variable.""" 121 return "true foo"
This is a @property
attribute. pdoc will display it as a variable.
123 @cached_property 124 def a_cached_property(self) -> str: 125 """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well.""" 126 return "true foo"
This is a @functools.cached_property
attribute. pdoc will display it as a variable as well.
128 @cache 129 def a_cached_function(self) -> str: 130 """This is method with `@cache` decoration.""" 131 return "true foo"
This is method with @cache
decoration.
133 @classmethod 134 def a_class_method(cls) -> int: 135 """This is what a `@classmethod` looks like.""" 136 return 24
This is what a @classmethod
looks like.
150class Bar(Foo): 151 bar: str 152 """A new attribute defined on this subclass.""" 153 154 class Baz: 155 """ 156 This class is an attribute of `Bar`. 157 To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation 158 (but not in the navigation). 159 160 It should be noted that inner classes are a pattern you most often want to avoid in Python. 161 Think about moving stuff in a new package instead! 162 163 This class has no __init__ method defined, so pdoc will not show a constructor. 164 """ 165 166 def wat(self): 167 """A regular method. Above, you see what happens if a class has no constructor defined and 168 no constructor docstring."""
Foo
is a basic class without any parent classes (except for the implicit object
class).
You will see in the definition of Bar
that docstrings are inherited by default.
Functions in the current scope can be referenced without prefix: a_regular_function()
.
154 class Baz: 155 """ 156 This class is an attribute of `Bar`. 157 To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation 158 (but not in the navigation). 159 160 It should be noted that inner classes are a pattern you most often want to avoid in Python. 161 Think about moving stuff in a new package instead! 162 163 This class has no __init__ method defined, so pdoc will not show a constructor. 164 """ 165 166 def wat(self): 167 """A regular method. Above, you see what happens if a class has no constructor defined and 168 no constructor docstring."""
This class is an attribute of Bar
.
To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation
(but not in the navigation).
It should be noted that inner classes are a pattern you most often want to avoid in Python. Think about moving stuff in a new package instead!
This class has no __init__ method defined, so pdoc will not show a constructor.
171async def i_am_async(self) -> int: 172 """ 173 This is an example of an async function. 174 175 - Knock, knock 176 - An async function 177 - Who's there? 178 """ 179 raise NotImplementedError
This is an example of an async function.
- Knock, knock
- An async function
- Who's there?
182@cache 183def fib(n): 184 """ 185 This is an example of decorated function. Decorators are included in the documentation as well. 186 This is often useful when documenting web APIs, for example. 187 """ 188 if n < 2: 189 return n 190 return fib(n - 1) + fib(n - 2)
This is an example of decorated function. Decorators are included in the documentation as well. This is often useful when documenting web APIs, for example.
193def security(test=os.environ): 194 """ 195 Default values are generally rendered using repr(), 196 but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data. 197 """ 198 return False
Default values are generally rendered using repr(), but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data.
201class DoubleInherit(Foo, Bar.Baz, abc.ABC): 202 """This is an example of a class that inherits from multiple parent classes."""
This is an example of a class that inherits from multiple parent classes.
A constant without type annotation
211@dataclass 212class DataDemo: 213 """ 214 This is an example for a dataclass. 215 216 As usual, you can link to individual properties: `DataDemo.a`. 217 """ 218 219 a: int 220 """Again, we can document individual properties with docstrings.""" 221 a2: Sequence[str] 222 # This property has a type annotation but is not documented. 223 a3 = "a3" 224 # This property has a default value but is not documented. 225 a4: str = "a4" 226 # This property has a type annotation and a default value but is not documented. 227 b: bool = field(repr=False, default=True) 228 """This property is assigned to `dataclasses.field()`, which works just as well."""
This is an example for a dataclass.
As usual, you can link to individual properties: DataDemo.a
.
237class EnumDemo(enum.Enum): 238 """ 239 This is an example of an Enum. 240 241 As usual, you can link to individual properties: `GREEN`. 242 """ 243 244 RED = 1 245 """I am the red.""" 246 GREEN = 2 247 """I am green.""" 248 BLUE = enum.auto()
This is an example of an Enum.
As usual, you can link to individual properties: GREEN
.
Inherited Members
- enum.Enum
- name
- value
251def embed_image(): 252 """ 253 This docstring includes an embedded image: 254 255 ``` 256 ![pdoc logo](../docs/logo.png) 257 ``` 258 259 ![pdoc logo](../../docs/logo.png) 260 """
This docstring includes an embedded image:
![pdoc logo](../docs/logo.png)
263def admonitions(): 264 """ 265 pdoc also supports basic reStructuredText admonitions: 266 267 ``` 268 .. note/warning/danger:: Optional title 269 Body text 270 ``` 271 272 .. note:: 273 Hi there! 274 275 .. warning:: Be Careful! 276 This warning has both a title and content. 277 278 .. danger:: 279 Danger ahead. 280 281 """
pdoc also supports basic reStructuredText admonitions:
.. note/warning/danger:: Optional title
Body text
Hi there!
Be Careful!
This warning has both a title and content.
Danger ahead.