demo_long API documentation

# 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.

View Source

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

FOO_CONSTANT: int = 42

A happy constant. ✨ pdoc documents constants with their type annotation and default value.

FOO_SINGLETON: Foo

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.

NO_DOCSTRING: int
def a_simple_function(a: str) -> str: View Source

    63def a_simple_function(a: str) -> str:
    64    """
    65    This is a basic module-level function.
    66
    67    For a more complex example, take a look at `a_complex_function`!
    68    """
    69    return a.upper()

This is a basic module-level function.

For a more complex example, take a look at `a_complex_function`!

def a_complex_function( first_argument: str, second_argument: Foo | str, *, keyword_only_argument: ~T) -> ~T: View Source

    75def a_complex_function(
    76    first_argument: str,
    77    second_argument: Foo | str,
    78    *,
    79    keyword_only_argument: T,
    80) -> T:
    81    """
    82    This is a function with a fairly complex signature,
    83    involving union types (|), a `typing.TypeVar` (~T),
    84    as well as a keyword-only arguments (*).
    85    """
    86    return keyword_only_argument

This is a function with a fairly complex signature, involving union types (|), a `typing.TypeVar` (~T), as well as a keyword-only arguments (*).

class Foo: View Source

     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: 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", keyword_only_argument=1)
    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")

`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()`.

Foo() View Source

    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", keyword_only_argument=1)

The constructor is currently always listed first as this feels most natural.

an_attribute: str | list[int]

A regular attribute with type annotations

a_class_attribute: ClassVar[str] = 'lots of foo!'

An attribute with a ClassVar annotation.

a_constructor_only_attribute: int

This attribute is defined in the constructor only, but still picked up by pdoc's AST traversal.

undocumented_constructor_attribute
def a_regular_function(self) -> Foo: View Source

    113    def a_regular_function(self) -> "Foo":
    114        """This is a regular method, returning the object itself."""
    115        return self

This is a regular method, returning the object itself.

a_property: str View Source

    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"

This is a `@property` attribute. pdoc will display it as a variable.

a_cached_property: str View Source

    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"

This is a `@functools.cached_property` attribute. pdoc will display it as a variable as well.

@cache
def a_cached_function(self) -> str: View Source

    127    @cache
    128    def a_cached_function(self) -> str:
    129        """This is method with `@cache` decoration."""
    130        return "true foo"

This is method with `@cache` decoration.

@classmethod
def a_class_method(cls) -> int: View Source

    132    @classmethod
    133    def a_class_method(cls) -> int:
    134        """This is what a `@classmethod` looks like."""
    135        return 24

This is what a `@classmethod` looks like.

a_class_property: int View Source

    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

This is what a `@classmethod @property` looks like.

@staticmethod
def a_static_method(): View Source

    143    @staticmethod
    144    def a_static_method():
    145        """This is what a `@staticmethod` looks like."""
    146        print("Hello World")

This is what a `@staticmethod` looks like.

class Bar(Foo): View Source

    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."""

`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()`.

bar: str

A new attribute defined on this subclass.

##### Inherited Members

Foo
  Foo
  an_attribute
  a_class_attribute
  a_constructor_only_attribute
  undocumented_constructor_attribute
  a_regular_function
  a_property
  a_cached_property
  a_cached_function
  a_class_method
  a_class_property
  a_static_method

class Bar.Baz: View Source

    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."""

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.

def wat(self): View Source

    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."""

A regular method. Above, you see what happens if a class has no constructor defined and no constructor docstring.

async def i_am_async(self) -> int: View Source

    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

This is an example of an async function.

- Knock, knock
- An async function
- Who's there?

@cache
def fib(n): View Source

    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)

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.

def security(test=os.environ): View Source

    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

Default values are generally rendered using repr(), but some special cases -- like os.environ -- are overridden to avoid leaking sensitive data.

class DoubleInherit(Foo, Bar.Baz, abc.ABC): View Source

    200class DoubleInherit(Foo, Bar.Baz, abc.ABC):
    201    """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.

##### Inherited Members

Foo
  Foo
  an_attribute
  a_class_attribute
  a_constructor_only_attribute
  undocumented_constructor_attribute
  a_regular_function
  a_property
  a_cached_property
  a_cached_function
  a_class_method
  a_class_property
  a_static_method
Bar.Baz
  wat

CONST_B = 'yes'

A constant without type annotation

CONST_NO_DOC = 'SHOULD NOT APPEAR'
@dataclass
class DataDemo: View Source

    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."""

This is an example for a dataclass.

As usual, you can link to individual properties: `DataDemo.a`.

DataDemo(a: int, a2: Sequence[str], a4: str = 'a4', b: bool = True)
a: int

Again, we can document individual properties with docstrings.

a2: Sequence[str]
a3 = 'a3'
a4: str = 'a4'
b: bool = True

This property is assigned to `dataclasses.field()`, which works just as well.

@dataclass
class DataDemoExtended(DataDemo): View Source

    230@dataclass
    231class DataDemoExtended(DataDemo):
    232    c: str = "42"
    233    """A new attribute."""

DataDemoExtended( a: int, a2: Sequence[str], a4: str = 'a4', b: bool = True, c: str = '42')
c: str = '42'

A new attribute.

##### Inherited Members

DataDemo
  a
  a2
  a3
  a4
  b

class EnumDemo(enum.Enum): View Source

    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()

This is an example of an Enum.

As usual, you can link to individual properties: `GREEN`.

RED = <EnumDemo.RED: 1>

I am the red.

GREEN = <EnumDemo.GREEN: 2>

I am green.

BLUE = <EnumDemo.BLUE: 3>
def embed_image(): View Source

    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    <img src="../docs/logo.png" alt="pdoc logo" width="150">
    262    ```
    263
    264    <img src="../../docs/logo.png" alt="pdoc logo" width="150">
    265    """

This docstring includes an embedded image:

    ![pdoc logo](../docs/logo.png)

    <img src="../docs/logo.png" alt="pdoc logo" width="150">

def admonitions(): View Source

    268def admonitions():
    269    """
    270    pdoc also supports basic reStructuredText admonitions or GitHub's Markdown alerts:
    271
    272    ```
    273    > [!NOTE/WARNING/DANGER]
    274    > Useful information that users should know, even when skimming content.
    275
    276    .. note/warning/danger:: Optional title
    277       Body text
    278    ```
    279
    280    > [!NOTE]
    281    > Hi there!
    282
    283    .. warning:: Be Careful!
    284       This warning has both a title *and* content.
    285
    286    .. danger::
    287       Danger ahead.
    288
    289    """

pdoc also supports basic reStructuredText admonitions or GitHub's Markdown alerts:

    > [!NOTE/WARNING/DANGER]
    > Useful information that users should know, even when skimming content.

    .. note/warning/danger:: Optional title
       Body text

Note

Hi there!

###### Be Careful!

This warning has both a title and content.

Danger ahead.