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""" 23from __future__ import annotations 24 25import abc 26import enum 27import os 28from dataclasses import dataclass, field 29from pdoc._compat import cached_property, cache 30from typing import Sequence, TypeVar, Union, ClassVar, Optional, List 31 32FOO_CONSTANT: int = 42 33""" 34A happy constant. ✨ 35pdoc documents constants with their type annotation and default value. 36""" 37 38FOO_SINGLETON: "Foo" 39""" 40This variable is annotated with a type only, but not assigned to a value. 41We also haven't defined the associated type (`Foo`) yet, 42so the type annotation in the code in the source code is actually a string literal: 43 44```python 45FOO_SINGLETON: "Foo" 46``` 47 48Similar to mypy, pdoc resolves 49[string forward references](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#class-name-forward-references) 50automatically. 51""" 52 53NO_DOCSTRING: int 54# this variable has a type annotation but not docstring, so it does not show up. 55 56 57def a_simple_function(a: str) -> str: 58 """ 59 This is a basic module-level function. 60 61 For a more complex example, take a look at `a_complex_function`! 62 """ 63 return a.upper() 64 65 66T = TypeVar("T") 67 68 69def a_complex_function( 70 a: str, b: Union["Foo", str], *, c: Optional[T] = None 71) -> Optional[T]: 72 """ 73 This is a function with a fairly complex signature, 74 involving type annotations with `typing.Union`, a `typing.TypeVar` (~T), 75 as well as a keyword-only arguments (*). 76 """ 77 return None 78 79 80class Foo: 81 """ 82 `Foo` is a basic class without any parent classes (except for the implicit `object` class). 83 84 You will see in the definition of `Bar` that docstrings are inherited by default. 85 86 Functions in the current scope can be referenced without prefix: `a_regular_function()`. 87 """ 88 89 an_attribute: Union[str, List["int"]] 90 """A regular attribute with type annotations""" 91 92 a_class_attribute: ClassVar[str] = "lots of foo!" 93 """An attribute with a ClassVar annotation.""" 94 95 def __init__(self): 96 """ 97 The constructor is currently always listed first as this feels most natural.""" 98 self.a_constructor_only_attribute: int = 42 99 """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.""" 100 101 self.undocumented_constructor_attribute = 42 102 a_complex_function() 103 104 def a_regular_function(self) -> "Foo": 105 """This is a regular method, returning the object itself.""" 106 return self 107 108 @property 109 def a_property(self) -> str: 110 """This is a `@property` attribute. pdoc will display it as a variable.""" 111 return "true foo" 112 113 @cached_property 114 def a_cached_property(self) -> str: 115 """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well.""" 116 return "true foo" 117 118 @cache 119 def a_cached_function(self) -> str: 120 """This is method with `@cache` decoration.""" 121 return "true foo" 122 123 @classmethod 124 def a_class_method(cls) -> int: 125 """This is what a `@classmethod` looks like.""" 126 return 24 127 128 @classmethod 129 @property 130 def a_class_property(cls) -> int: 131 """This is what a `@classmethod @property` looks like.""" 132 return 24 133 134 @staticmethod 135 def a_static_method(): 136 """This is what a `@staticmethod` looks like.""" 137 print("Hello World") 138 139 140class Bar(Foo): 141 bar: str 142 """A new attribute defined on this subclass.""" 143 144 class Baz: 145 """ 146 This class is an attribute of `Bar`. 147 To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation 148 (but not in the navigation). 149 150 It should be noted that inner classes are a pattern you most often want to avoid in Python. 151 Think about moving stuff in a new package instead! 152 153 Below, you see what happens if a class has no constructor defined (and hence no constructor docstring). 154 """ 155 156 def wat(self): 157 """A regular method. Above, you see what happens if a class has no constructor defined and 158 no constructor docstring.""" 159 160 161async def i_am_async(self) -> int: 162 """ 163 This is an example of an async function. 164 165 - Knock, knock 166 - An async function 167 - Who's there? 168 """ 169 170 171@cache 172def fib(n): 173 """ 174 This is an example of decorated function. Decorators are included in the documentation as well. 175 This is often useful when documenting web APIs, for example. 176 """ 177 if n < 2: 178 return n 179 return fib(n - 1) + fib(n - 2) 180 181 182def security(test=os.environ): 183 """ 184 Default values are generally rendered using repr(), 185 but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data. 186 """ 187 return False 188 189 190class DoubleInherit(Foo, Bar.Baz, abc.ABC): 191 """This is an example of a class that inherits from multiple parent classes.""" 192 193 194CONST_B = "yes" 195"""A constant without type annotation""" 196 197CONST_NO_DOC = "SHOULD NOT APPEAR" 198 199 200@dataclass 201class DataDemo: 202 """ 203 This is an example for a dataclass. 204 Dataclasses generate a relatively pointless docstring by default, 205 but you can override it by providing your own (like here!). 206 207 As usual, you can link to individual properties: `DataDemo.a`. 208 """ 209 210 a: int 211 """Again, we can document individual properties with docstrings.""" 212 a2: Sequence[str] 213 # This property has a type annotation but is not documented, so it does not show up. 214 b: bool = field(repr=False, default=True) 215 """This property is assigned to `dataclasses.field()`, which works just as well.""" 216 217 218class EnumDemo(enum.Enum): 219 """ 220 This is an example of an Enum. 221 222 As usual, you can link to individual properties: `GREEN`. 223 """ 224 225 RED = 1 226 """I am the red.""" 227 GREEN = 2 228 """I am green.""" 229 BLUE = enum.auto() 230 """I am blue."""
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.
58def a_simple_function(a: str) -> str: 59 """ 60 This is a basic module-level function. 61 62 For a more complex example, take a look at `a_complex_function`! 63 """ 64 return a.upper()
This is a basic module-level function.
For a more complex example, take a look at a_complex_function
!
70def a_complex_function( 71 a: str, b: Union["Foo", str], *, c: Optional[T] = None 72) -> Optional[T]: 73 """ 74 This is a function with a fairly complex signature, 75 involving type annotations with `typing.Union`, a `typing.TypeVar` (~T), 76 as well as a keyword-only arguments (*). 77 """ 78 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 (*).
81class Foo: 82 """ 83 `Foo` is a basic class without any parent classes (except for the implicit `object` class). 84 85 You will see in the definition of `Bar` that docstrings are inherited by default. 86 87 Functions in the current scope can be referenced without prefix: `a_regular_function()`. 88 """ 89 90 an_attribute: Union[str, List["int"]] 91 """A regular attribute with type annotations""" 92 93 a_class_attribute: ClassVar[str] = "lots of foo!" 94 """An attribute with a ClassVar annotation.""" 95 96 def __init__(self): 97 """ 98 The constructor is currently always listed first as this feels most natural.""" 99 self.a_constructor_only_attribute: int = 42 100 """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.""" 101 102 self.undocumented_constructor_attribute = 42 103 a_complex_function() 104 105 def a_regular_function(self) -> "Foo": 106 """This is a regular method, returning the object itself.""" 107 return self 108 109 @property 110 def a_property(self) -> str: 111 """This is a `@property` attribute. pdoc will display it as a variable.""" 112 return "true foo" 113 114 @cached_property 115 def a_cached_property(self) -> str: 116 """This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well.""" 117 return "true foo" 118 119 @cache 120 def a_cached_function(self) -> str: 121 """This is method with `@cache` decoration.""" 122 return "true foo" 123 124 @classmethod 125 def a_class_method(cls) -> int: 126 """This is what a `@classmethod` looks like.""" 127 return 24 128 129 @classmethod 130 @property 131 def a_class_property(cls) -> int: 132 """This is what a `@classmethod @property` looks like.""" 133 return 24 134 135 @staticmethod 136 def a_static_method(): 137 """This is what a `@staticmethod` looks like.""" 138 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()
.
96 def __init__(self): 97 """ 98 The constructor is currently always listed first as this feels most natural.""" 99 self.a_constructor_only_attribute: int = 42 100 """This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.""" 101 102 self.undocumented_constructor_attribute = 42 103 a_complex_function()
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.
105 def a_regular_function(self) -> "Foo": 106 """This is a regular method, returning the object itself.""" 107 return self
This is a regular method, returning the object itself.
This is a @functools.cached_property
attribute. pdoc will display it as a variable as well.
119 @cache 120 def a_cached_function(self) -> str: 121 """This is method with `@cache` decoration.""" 122 return "true foo"
This is method with @cache
decoration.
141class Bar(Foo): 142 bar: str 143 """A new attribute defined on this subclass.""" 144 145 class Baz: 146 """ 147 This class is an attribute of `Bar`. 148 To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation 149 (but not in the navigation). 150 151 It should be noted that inner classes are a pattern you most often want to avoid in Python. 152 Think about moving stuff in a new package instead! 153 154 Below, you see what happens if a class has no constructor defined (and hence no constructor docstring). 155 """ 156 157 def wat(self): 158 """A regular method. Above, you see what happens if a class has no constructor defined and 159 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()
.
145 class Baz: 146 """ 147 This class is an attribute of `Bar`. 148 To not create overwhelmingly complex trees, pdoc flattens the class hierarchy in the documentation 149 (but not in the navigation). 150 151 It should be noted that inner classes are a pattern you most often want to avoid in Python. 152 Think about moving stuff in a new package instead! 153 154 Below, you see what happens if a class has no constructor defined (and hence no constructor docstring). 155 """ 156 157 def wat(self): 158 """A regular method. Above, you see what happens if a class has no constructor defined and 159 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!
Below, you see what happens if a class has no constructor defined (and hence no constructor docstring).
162async def i_am_async(self) -> int: 163 """ 164 This is an example of an async function. 165 166 - Knock, knock 167 - An async function 168 - Who's there? 169 """
This is an example of an async function.
- Knock, knock
- An async function
- Who's there?
172@cache 173def fib(n): 174 """ 175 This is an example of decorated function. Decorators are included in the documentation as well. 176 This is often useful when documenting web APIs, for example. 177 """ 178 if n < 2: 179 return n 180 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.
183def security(test=os.environ): 184 """ 185 Default values are generally rendered using repr(), 186 but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data. 187 """ 188 return False
Default values are generally rendered using repr(), but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data.
191class DoubleInherit(Foo, Bar.Baz, abc.ABC): 192 """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
201@dataclass 202class DataDemo: 203 """ 204 This is an example for a dataclass. 205 Dataclasses generate a relatively pointless docstring by default, 206 but you can override it by providing your own (like here!). 207 208 As usual, you can link to individual properties: `DataDemo.a`. 209 """ 210 211 a: int 212 """Again, we can document individual properties with docstrings.""" 213 a2: Sequence[str] 214 # This property has a type annotation but is not documented, so it does not show up. 215 b: bool = field(repr=False, default=True) 216 """This property is assigned to `dataclasses.field()`, which works just as well."""
This is an example for a dataclass. Dataclasses generate a relatively pointless docstring by default, but you can override it by providing your own (like here!).
As usual, you can link to individual properties: DataDemo.a
.
219class EnumDemo(enum.Enum): 220 """ 221 This is an example of an Enum. 222 223 As usual, you can link to individual properties: `GREEN`. 224 """ 225 226 RED = 1 227 """I am the red.""" 228 GREEN = 2 229 """I am green.""" 230 BLUE = enum.auto() 231 """I am blue."""
This is an example of an Enum.
As usual, you can link to individual properties: GREEN
.
Inherited Members
- enum.Enum
- name
- value