### Running an Example Script

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

This example shows how to execute a Python script that likely interacts with mitmproxy. Ensure the script is executable and mitmproxy is set up correctly.

```bash
$ python example_numpy.py

```

--------------------------------

### ExampleClass.__init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

Example of docstring formatting for a constructor.

```APIDOC
## ExampleClass.__init__(self, param1, param2, param3)

### Description
Example of docstring formatting for a constructor.

### Parameters
* **self**: 
* **param1**: Type not specified.
* **param2**: Type not specified.
* **param3**: Type not specified.

### Returns
Type not specified.
```

--------------------------------

### Install pdoc

Source: https://github.com/mitmproxy/pdoc/blob/main/README.md

Install pdoc using pip. Compatible with Python 3.10 and newer.

```shell
pip install pdoc
```

--------------------------------

### Async Function Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demo_long.html

Shows an example of an asynchronous function. pdoc includes docstrings and type hints for async functions.

```python
async def i_am_async(self) -> int:
    """
    This is an example of an async function.

    - Knock, knock
    - An async function
    - Who's there?
    """
    raise NotImplementedError
```

--------------------------------

### ExampleClass

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Example class demonstrating documentation for class-level attributes and the __init__ method.

```APIDOC
## ExampleClass

### Description
An example class with documented attributes and an initializer.

### Parameters
#### Path Parameters
- **param1** (type) - Required - Description of param1.
- **param2** (type) - Required - Description of param2.
- **param3** (type) - Required - Description of param3.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **None**: No specific return value documented for the class itself.

#### Response Example
```json
{
  "example": "response body"
}
```

### Attributes
- **attr1** (str) - Description of `attr1`.
- **attr2** (:obj:`int`, optional) - Description of `attr2`.
```

--------------------------------

### Clone Repository and Run Help Command

Source: https://github.com/mitmproxy/pdoc/blob/main/CONTRIBUTING.md

Clone the pdoc repository and verify the installation by running the help command. This is the initial step for setting up your development environment.

```shell
git clone https://github.com/mitmproxy/pdoc.git
cd pdoc
uv run pdoc --help
```

--------------------------------

### Example Note with Markdown Admonition

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demo_long.html

A simple example of a Markdown note admonition.

```markdown
> [!NOTE]
> Hi there!
```

--------------------------------

### keyword_arguments

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

This an example for keyword arguments.

```APIDOC
## keyword_arguments(**kwargs)

### Description
This an example for keyword arguments.

### Parameters
* **kwargs**: Arbitrary keyword arguments.

### Returns
Type not specified.
```

--------------------------------

### example_generator

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

A generator function for examples.

```APIDOC
## example_generator

### Description
This is a generator function that yields example values.

### Yields
[Description of yielded values]
```

--------------------------------

### Example Code Snippet (Python)

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

A simple Python code example demonstrating variable assignments, potentially for testing documentation rendering.

```python
tmp = a2()

tmp2 = a()

```

--------------------------------

### Documenting Code Examples with Literal Blocks

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Use literal blocks (::) in reStructuredText to include code examples. This method supports any reStructuredText formatting.

```rst
Examples can be given using either the `Example` or `Examples` sections. Sections support any reStructuredText formatting, including literal blocks::

    $ python example_google.py
    
```

--------------------------------

### ExampleError

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

A custom exception class for examples.

```APIDOC
## ExampleError

### Description
A custom exception class used for demonstrating error handling.

### Methods
*   `__init__(...)`: Initializes the ExampleError.
*   `msg()`: Returns the error message.
*   `code()`: Returns the error code.
*   `add_note(...)`: Adds a note to the error.
*   `with_traceback(...)`: Sets the traceback for the error.
```

--------------------------------

### Module Level Function Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

This function demonstrates how to document parameters, return values, and exceptions using reStructuredText. It includes examples of required and optional parameters, variable arguments, and specific exception handling.

```python
def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the `Parameters` section.
    The name of each parameter is required. The type and description of each
    parameter is optional, but should be included if not obvious.

    If *args or **kwargs are accepted,
    they should be listed as `*args` and `**kwargs`.

    The format for a parameter is::

        name : type
            description
        
            The description may span multiple lines. Following lines
            should be indented to match the first line of the description.
            The ": type" is optional.
        
            Multiple paragraphs are supported in parameter
            descriptions.
    
    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : :obj:`str`, optional
        The second parameter.
    *args
        Variable length argument list.
    **kwargs
        Arbitrary keyword arguments.

    Returns
    -------
    bool
        True if successful, False otherwise.

        The return type is not optional. The `Returns` section may span
        multiple lines and paragraphs. Following lines should be indented to
        match the first line of the description.

        The `Returns` section supports any reStructuredText formatting,
        including literal blocks::

            {
                'param1': param1,
                'param2': param2
            }

    Raises
    ------
    AttributeError
        The `Raises` section is a list of all exceptions
        that are relevant to the interface.
    ValueError
        If `param2` is equal to `param1`.

    """
    if param1 == param2:
        raise ValueError('param1 may not be equal to param2')
    return True
```

--------------------------------

### Python @staticmethod

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demo_long.html

Documentation example for a Python static method.

```python
@staticmethod
def a_static_method():
    """This is what a `@staticmethod` looks like."""
    print("Hello World")
```

--------------------------------

### NamedTupleExample Class

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc_py312.txt

Documentation for the NamedTupleExample class, an example of a typing.NamedTuple.

```APIDOC
## class misc_py312.NamedTupleExample

### Description
An example for a typing.NamedTuple.

### Methods
#### def __init__(self, name: str, id: int = 3)

##### Description
Create new instance of NamedTupleExample(name, id)

##### Parameters
- **name** (str) - Required - Name of our example tuple
- **id** (int) - Optional - Alias for field number

#### def index(self, value, start=0, stop=9223372036854775807, /)

##### Description
inherited from builtins.tuple.index, Return first index of value. Raises ValueError if not found.

##### Parameters
- **value** - The value to search for.
- **start** (int) - Optional - The starting index of the slice to search.
- **stop** (int) - Optional - The ending index of the slice to search.

#### def count(self, value, /)

##### Description
inherited from builtins.tuple.count, Return number of occurrences of value.

##### Parameters
- **value** - The value to count.
```

--------------------------------

### Python Code Block Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_rst.html

Demonstrates a simple Python code block within documentation.

```python
def seealso():
    # this is not properly supported yet
    """
    .. seealso::

       Module :py:mod:`zipfile`
          Documentation of the :py:mod:`zipfile` standard module.

       `GNU tar manual, Basic Tar Format <http://link>`_
          Documentation for tar archive files, including GNU tar extensions.
    """
```

--------------------------------

### NamedTupleExample

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc_py312.html

An example demonstrating the use of typing.NamedTuple for structured data.

```APIDOC
## NamedTupleExample

### Description
An example for a typing.NamedTuple.

### Fields
- **name** (str) - Description: Name of our example tuple.
- **id** (int) - Description: Alias for field number 1. Defaults to 3.
```

--------------------------------

### example_code

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

A function that includes example code in its docstring.

```APIDOC
## example_code

### Description
This function's docstring contains an embedded code example.

### Parameters
[Parameters, if any]

### Returns
[Return value, if any]

### Example
```python
# Example usage
print('Hello, world!')
```
```

--------------------------------

### ExampleError

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

A custom exception class for example errors.

```APIDOC
## ExampleError

### Description
Custom exception class for example-related errors.

### Parameters
#### Path Parameters
- **msg** (str) - Required - Human readable string describing the exception.
- **code** (int) - Optional - Numeric error code.

### Attributes
- **msg** (str) - Human readable string describing the exception.
- **code** (int) - Numeric error code.
```

--------------------------------

### Descriptor Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Demonstrates a custom descriptor class used to manage attribute access and documentation.

```python
class Descriptor:
    def __init__(self, func):
        self.__doc__ = func.__doc__

    def __get__(self, instance, owner):
        return self if instance is None else getattr(instance, "_x", 0)

    def __set__(self, instance, value):
        instance._x = value
```

```python
class Issue226:
    @Descriptor
    def size(self):
        """This is the size"""
        pass
```

--------------------------------

### Python Metaclass __call__ Example 1

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Illustrates a class with a metaclass that defines `__call__`, where `__init__` is preferred.

```python
class Issue352aMeta(type):
    def __call__(cls, *args, **kwargs):
        """Meta.__call__"""

class Issue352a(metaclass=Issue352aMeta):
    def __init__(self):
        """Issue352.__init__ should be preferred over Meta.__call__."""

```

--------------------------------

### Include Options Function

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_rst.html

Demonstrates how to include options from another file using include directives. Supports specifying start and end lines or markers.

```python
def include_options():
    """
    Included from another file:

    .. include:: flavors_rst_include/include_2.md
       :start-line: 2
       :end-line: 5


    Also included:

    .. include:: flavors_rst_include/include_2.md
       :start-after: <!-- start here -->
       :end-before: <!-- end here -->
    """
    raise NotImplementedError
```

--------------------------------

### Python Metaclass __call__ Example 2

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Shows a class with a metaclass defining `__call__` but no `__init__` docstring.

```python
class Issue352bMeta(type):
    def __call__(cls, *args, **kwargs):
        pass

class Issue352b(metaclass=Issue352bMeta):
    """No docstrings for the constructor here."""

```

--------------------------------

### Classmethod Example with Docstring

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Illustrates a class 'ClassmethodLink' with a classmethod 'bar'. The docstring explains how to call it and notes that neither method call nor the method itself will be linked.

```python
class ClassmethodLink:
    """
    You can either do

    >>> ClassmethodLink.bar()
    42

    or

    ```python
    ClassmethodLink.bar()
    ```

    neither will be linked.
    """

    @classmethod
    def bar(cls):
        return 42

```

--------------------------------

### Broken Math Mode Rendering in Markdown

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/math_misc.html

Shows an example where Markdown's math mode incorrectly interprets lines starting with '#' as headings. This is the problematic rendering.

```markdown
$$ \newcommand{\define}\[2\] {
#1 \quad \text{#2}
}
\define{e^{i\pi}+1=0}{Euler's identity} $$
```

--------------------------------

### Docstring Inheritance Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Illustrates docstring inheritance for methods, properties, and class attributes across base and child classes.

```python
class Base:
    def __init__(self):
        """init"""
        super().__init__()

    def foo(self):
        """foo"""
        pass

    @classmethod
    def bar(cls):
        """bar"""
        pass

    @staticmethod
    def baz():
        """baz"""
        pass

    @property
    def qux(self):
        """qux"""
        return

    @cached_property
    def quux(self):
        """quux"""
        return

    quuux: int = 42
    """quuux"""
```

```python
class Child(Base):
    def __init__(self):
        super().__init__()

    def foo(self):
        pass

    @classmethod
    def bar(cls):
        pass

    @staticmethod
    def baz():
        pass

    @property
    def qux(self):
        return

    @cached_property
    def quux(self):
        return

    quuux: int = 42
```

--------------------------------

### module_level_function

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

This is an example of a module level function. Function parameters should be documented in the `Args` section. The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious. If *args or **kwargs are accepted, they should be listed as `*args` and `**kwargs`.

```APIDOC
## module_level_function(param1, param2=None, *args, **kwargs)

### Description
This is an example of a module level function. Function parameters should be documented in the `Args` section. The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious. If *args or **kwargs are accepted, they should be listed as `*args` and `**kwargs`.

### Parameters
#### Arguments
*   **param1** (int) - Required - The first parameter.
*   **param2** (str) - Optional - The second parameter. Defaults to None.
    Second line of description should be indented.
*   **args** - Variable length argument list.
*   **kwargs** - Arbitrary keyword arguments.

### Returns
*   **bool**: True if successful, False otherwise.

    The return type is optional and may be specified at the beginning of the `Returns` section followed by a colon.

    The `Returns` section may span multiple lines and paragraphs. Following lines should be indented to match the first line.

    The `Returns` section supports any reStructuredText formatting, including literal blocks::

        {
            'param1': param1,
            'param2': param2
        }

### Raises
*   **AttributeError**: The `Raises` section is a list of all exceptions that are relevant to the interface.
*   **ValueError**: If `param2` is equal to `param1`.
```

--------------------------------

### Python Private Member Docstring Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Demonstrates a private method in Python with a docstring. By default, private members (those starting with an underscore, excluding special methods) are not included in documentation output. This behavior can be altered in Sphinx configuration.

```python
def _private(self):
    """By default private members are not included.

    Private members are any methods or attributes that start with an
    underscore and are *not* special. By default they are not included
    in the output.

    This behavior can be changed such that private members *are* included
    by changing the following setting in Sphinx's conf.py::

        napoleon_include_private_with_doc = True

    """
    pass
```

--------------------------------

### Generic Base Class Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Demonstrates the definition and usage of generic base classes and their non-generic children.

```python
T = TypeVar("T")

class GenericParent(Generic[T]):
    """GenericParent"""
    pass

class NonGenericChild(GenericParent[str]):
    """NonGenericChild"""
    pass
```

--------------------------------

### Dog.__init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/example_darkmode.html

Initializes a new Dog instance.

```APIDOC
## Method: Dog.__init__

### Description
Make a Dog without any friends (yet).

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the dog.
```

--------------------------------

### Single Dispatch Method Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Illustrates the use of functools.singledispatchmethod for creating methods that dispatch based on argument type.

```python
import functools

class SingleDispatchMethodExample:
    @functools.singledispatchmethod
    def fancymethod(self, str_or_int: str | int):
        """A fancy method which is capable of handling either `str` or `int`.

        :param str_or_int: string or integer to handle
        """
        raise NotImplementedError(f"{type(str_or_int)=} not implemented!")

    @fancymethod.register
    def fancymethod_handle_str(self, str_to_handle: str):
        """Fancy method handles a string.

        :param str_to_handle: string which will be handled
        """
        print(f"{type(str_to_handle)} = '{str_to_handle}")

    @fancymethod.register
    def _fancymethod_handle_int(self, int_to_handle: int):
        """Fancy method handles int (not shown in doc).

        :param int_to_handle: int which will be handled
        """

```

--------------------------------

### Decorated Function Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Shows an example of a function decorated by a class decorator. This decorated function may not be documented correctly.

```python
another_decorated_function = <[ClassDecorator](#ClassDecorator) object>
```

--------------------------------

### ExampleClass Constructor

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Initializes an instance of ExampleClass with specified parameters and provides detailed documentation for each.

```APIDOC
## ExampleClass(param1, param2, param3)

### Description
Initializes an instance of ExampleClass. The docstring for `__init__` can be at the class level or on the method itself. Ensure consistency in documentation style.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
__init__

### Endpoint
N/A (Class constructor)

### Parameters
#### Args
*   **param1** (str) - Required - Description of `param1`.
*   **param2** (:obj:`int`, optional) - Optional - Description of `param2`. Multiple lines are supported.
*   **param3** (:obj:`list` of :obj:`str`) - Required - Description of `param3`.

### Attributes
*   **attr1** (str): Description of `attr1`.
*   **attr2** (`int`, optional): Description of `attr2`.
*   **attr3**: Doc comment *inline* with attribute.
*   **attr4** (list of str): Doc comment *before* attribute, with type specified.
*   **attr5**: Docstring *after* attribute, with type specified.
```

--------------------------------

### Module Docstring with Google Style

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

This docstring demonstrates the overall structure for module documentation using Google style, including sections for examples, attributes, and TODOs.

```python
"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:
   http://google.github.io/styleguide/pyguide.html

"""
__docformat__ = "google"

```

--------------------------------

### ExampleClass Initialization

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Initializes ExampleClass with parameters and documents attributes inline and before declaration.

```python
class ExampleClass(object):
    """The summary line for a class docstring should fit on one line.

    If the class has public attributes, they may be documented here
    in an `Attributes` section and follow the same formatting as a
    function's `Args` section. Alternatively, attributes may be documented
    inline with the attribute's declaration (see __init__ method below).

    Properties created with the `@property` decorator should be documented
    in the property's getter method.

    Attributes:
        attr1 (str): Description of `attr1`.
        attr2 (:obj:`int`, optional): Description of `attr2`.

    """

    def __init__(self, param1, param2, param3):
        """Example of docstring on the __init__ method.

        The __init__ method may be documented in either the class level
        docstring, or as a docstring on the __init__ method itself.

        Either form is acceptable, but the two should not be mixed. Choose one
        convention to document the __init__ method and be consistent with it.

        Note:
            Do not include the `self` parameter in the `Args` section.

        Args:
            param1 (str): Description of `param1`.
            param2 (:obj:`int`, optional): Description of `param2`. Multiple
                lines are supported.
            param3 (:obj:`list` of :obj:`str`): Description of `param3`.

        """
        self.attr1 = param1
        self.attr2 = param2
        self.attr3 = param3  #: Doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr4 = ['attr4']

        self.attr5 = None
        """str: Docstring *after* attribute, with type specified."""
```

--------------------------------

### Python Docstring with Links

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Example docstring containing various types of links, including explicit and implicit references.

```python
# Adapted from https://github.com/mitmproxy/pdoc/issues/335
def linkify_links():
    """
    This docstring contains links that are also identifiers:

    - [`linkify_links`](https://example.com/)
    - [misc.linkify_links](https://example.com/)
    - [`linkify_links()`](https://example.com/)
    - [misc.linkify_links()](https://example.com/)
    - [link in target](https://example.com/misc.linkify_links)
    - [explicit linking](#AbstractClass.foo)
    """

```

--------------------------------

### Module Level Function Documentation

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

This is an example of a module-level function. Function parameters should be documented in the Parameters section, and the name of each parameter is required.

```python
def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    Function parameters should be documented in the `Parameters` section.
    The name of each parameter is required. The type and description of each
    
```

--------------------------------

### ExampleClass Constructor

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Initializes an instance of ExampleClass with specified parameters.

```APIDOC
## ExampleClass(param1, param2, param3)

### Description
Initializes an instance of ExampleClass. The docstring for \`__init__\` can be on the class level or the method itself.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters

- **param1** (str) - Description of `param1`.
- **param2** (list of str) - Description of `param2`. Multiple lines are supported.
- **param3** (int, optional) - Description of `param3`.

### Attributes

- **attr1** (str): Description of `[attr1](#ExampleClass.attr1)`.
- **attr2** (int, optional): Description of `[attr2](#ExampleClass.attr2)`.
- **attr3**: Doc comment *inline* with attribute
- **attr4** (list of str): Doc comment *before* attribute, with type specified
- **attr5** (str): Docstring *after* attribute, with type specified.

### Request Example
```python
# Example instantiation (actual code not provided in source)
# instance = ExampleClass(param1='value1', param2=['a', 'b'], param3=10)
```

### Response
#### Success Response (200)
None (Constructor does not return a value in this context)

#### Response Example
None
```

--------------------------------

### Example code for issue 264

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Provides example code related to issue #264 on GitHub. This snippet is intended for testing docstring parsing.

```python
def example_code():
    """
    Test case for https://github.com/mitmproxy/pdoc/issues/264.

    Example:

        ```python
        tmp = a2()

        tmp2 = a()
        ```
    """
```

--------------------------------

### ExampleClass.example_method

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Documentation for the example_method of ExampleClass.

```APIDOC
## example_method(self, param1, param2)

### Description
Class methods are similar to regular functions.

Note
----
Do not include the `self` parameter in the `Parameters` section.

### Parameters
- **param1** - The first parameter.
- **param2** - The second parameter.

### Returns
- **bool** - True if successful, False otherwise.
```

--------------------------------

### Dog.__init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demo.html

Initializes a new Dog instance. It takes a name and optionally sets up an empty list for friends.

```APIDOC
## Dog.__init__

### Description
Make a Dog without any friends (yet).

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of our dog.

#### Query Parameters
- **friends** (list[Dog]) - Optional - The friends of our dog.
```

--------------------------------

### foo Function

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

This function demonstrates a comprehensive docstring structure, including parameters, return values, exceptions, see also, notes, and examples.

```APIDOC
## foo(var1, var2, *args, long_var_name='hi', **kwargs)

### Description
Summarize the function in one line.

Several sentences providing an extended description. Refer to
variables using back-ticks, e.g. `var`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **var1** (array_like) - Array_like means all those objects -- lists, nested lists, etc. -- that can be converted to an array.  We can also refer to variables like `var1`.
- **var2** (int) - The type above can either refer to an actual Python type (e.g. `int`), or describe the type of the variable in more detail, e.g. `(N,) ndarray` or `array_like`.
- **args** (iterable) - Other arguments.
- **long_var_name** ({'hi', 'ho'}, optional) - Choices in brackets, default first when optional.
- **kwargs** (dict) - Keyword arguments.

### Returns
- **type** - Explanation of anonymous return value of type `type`.
- **describe** (type) - Explanation of return value named `describe`.
- **out** (type) - Explanation of `out`.
- **type_without_description** - No description provided.

### Other Parameters
- **only_seldom_used_keywords** (type) - Explanation.
- **common_parameters_listed_above** (type) - Explanation.

### Raises
- **BadException** - Because you shouldn't have done that.

### See Also
- numpy.array : Relationship (optional).
- numpy.ndarray : Relationship (optional), which could be fairly long, in which case the line wraps here.
- numpy.dot, numpy.linalg.norm, numpy.eye

### Notes
Notes about the implementation algorithm (if needed).

This can have multiple paragraphs.

You may include some math:

.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}

And even use a Greek symbol like :math:`\omega` inline.

### References
Cite the relevant literature, e.g. [1]_.  You may also cite these references in the notes section above.

.. [1] O. McNoleg, "The integration of GIS, remote sensing, expert systems and adaptive co-kriging for environmental habitat modelling of the Highland Haggis using object-oriented, fuzzy-logic and neural-network techniques," Computers & Geosciences, vol. 22, pp. 585-588, 1996.

### Examples
These are written in doctest format, and should illustrate how to use the function.

```python
>>> a = [1, 2, 3]
>>> print([x + 3 for x in a])
[4, 5, 6]
>>> print("a\nb")
a
b
```
```

--------------------------------

### module_level_function

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

This is an example of a module level function. It demonstrates how to document parameters, variable arguments, and return values using a specific format.

```APIDOC
## module_level_function(param1, param2=None, *args, **kwargs)

### Description
This function serves as an example for documenting module-level functions. It illustrates the expected format for parameter and return value documentation.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Positional Parameters
*   **param1** (int) - Required - The first parameter.
*   **param2** (:obj:`str`, optional) - Optional - The second parameter.
*   **\*args** - Variable length argument list.
*   **\*\*kwargs** - Arbitrary keyword arguments.

### Returns
#### Success Response (200)
*   **bool** - True if successful, False otherwise.

### Raises
*   **AttributeError** - The `Raises` section is a list of all exceptions that are relevant to the interface.
*   **ValueError** - If `param2` is equal to `param1`.
```

--------------------------------

### Initialize ExampleError

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Constructor for ExampleError, taking a message and an error code.

```python
def __init__(self, msg, code):
        self.msg = msg
        self.code = code
```

--------------------------------

### Python List Comprehension Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Illustrates a basic Python list comprehension for transforming elements and printing output. This example is suitable for demonstrating fundamental Python operations.

```python
>>> a = [1, 2, 3]
>>> print([x + 3 for x in a])
[4, 5, 6]
>>> print("a\nb")
a b
```

--------------------------------

### ExampleClass

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Documentation for the ExampleClass, including its constructor, attributes, and properties.

```APIDOC
## ExampleClass

### Description
A sample class demonstrating various documentation conventions for attributes, methods, and properties.

### Attributes
*   **attr1** (str): Description of `attr1`.
*   **attr2** (:obj:`list` of :obj:`str`, optional): Description of `attr2`.
*   **attr3** (str): Doc comment *inline* with attribute.
*   **attr4** (list of str): Doc comment *before* attribute, with type specified.
*   **attr5** (str): Docstring *after* attribute, with type specified.

### Methods
#### `__init__(self, param1, param2, param3)`
Initializes a new instance of the ExampleClass.

Parameters:
*   **param1** (str) - Description of `param1`.
*   **param2** (:obj:`list` of :obj:`str`) - Description of `param2`.
*   **param3** (:obj:`int`, optional) - Description of `param3`.

### Properties
#### `readonly_property`
*   **Type**: str
*   **Description**: Properties should be documented in their getter method.

#### `readwrite_property`
*   **Type**: :obj:`list` of :obj:`str`
*   **Description**: Properties with both a getter and setter.
```

--------------------------------

### example_code

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

Test case for https://github.com/google/styleguide/issues/171

```APIDOC
## example_code()

### Description
Test case for https://github.com/google/styleguide/issues/171

### Parameters
None

### Returns
Type not specified.
```

--------------------------------

### SampleClass.__init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

Inits SampleClass with optional spam liking.

```APIDOC
## SampleClass.__init__(self, likes_spam=False)

### Description
Inits SampleClass with optional spam liking.

### Parameters
* **self**: 
* **likes_spam** (bool) - Optional - Defaults to False.

### Returns
Type not specified.
```

--------------------------------

### ExampleError.__init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

Initializes an instance of ExampleError.

```APIDOC
## ExampleError.__init__(self, msg, code)

### Description
Initializes an instance of ExampleError.

### Parameters
* **self**: 
* **msg**: Type not specified.
* **code**: Type not specified.

### Returns
Type not specified.
```

--------------------------------

### module_level_function

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

This is an example of a module-level function.

```APIDOC
## module_level_function(param1, param2=None, *args, **kwargs)

### Description
This is an example of a module-level function.

### Parameters
* **param1**: Type not specified.
* **param2**: Type not specified. Defaults to None.
* **args**: Variable length argument list.
* **kwargs**: Arbitrary keyword arguments.

### Returns
Type not specified.
```

--------------------------------

### ExampleClass

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

A sample class for demonstration purposes.

```APIDOC
## ExampleClass

### Description
This class serves as an example for demonstrating various class features.

### Methods
*   `__init__(...)`: Constructor for ExampleClass.
*   `example_method(...)`: A sample method within the class.

### Properties
*   `readonly_property`: A read-only property.
*   `readwrite_property`: A read-write property.

### Attributes
*   `attr1`: Description of attr1.
*   `attr2`: Description of attr2.
*   `attr3`: Description of attr3.
*   `attr4`: Description of attr4.
*   `attr5`: Description of attr5.
```

--------------------------------

### Foo

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demo_long.html

A sample class with various methods and attributes.

```APIDOC
## Foo

### Description
A sample class with various methods and attributes.

### Methods
#### __init__(self, constructor_only_arg)
Constructor for the Foo class.

* **constructor_only_arg** (str) - Required - Argument only for the constructor.

#### a_regular_function(self, arg1, arg2)
A regular function within the Foo class.

* **arg1** (int) - Required - Description of arg1.
* **arg2** (list) - Optional - Description of arg2.

#### a_class_method(cls, cls_arg)
A class method of the Foo class.

* **cls_arg** (dict) - Required - Description of cls_arg.

#### a_static_method(static_arg)
A static method of the Foo class.

* **static_arg** (float) - Required - Description of static_arg.

### Attributes
#### an_attribute
Description of an_attribute.

#### a_class_attribute
Description of a_class_attribute.

#### a_constructor_only_attribute
Description of a_constructor_only_attribute.

#### a_property
Description of a_property.

#### a_cached_property
Description of a_cached_property.

#### a_cached_function
Description of a_cached_function.

#### a_class_property
Description of a_class_property.
```

--------------------------------

### invalid_format

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

In this example, the docstring format is invalid.

```APIDOC
## invalid_format(test)

### Description
In this example, the docstring format is invalid.

### Parameters
* **test**: Type not specified.

### Returns
Type not specified.
```

--------------------------------

### Run Basic Test Suite with Tox

Source: https://github.com/mitmproxy/pdoc/blob/main/CONTRIBUTING.md

Execute the project's test suite using tox after setting up the development environment. Ensure all tests pass to maintain 100% test coverage.

```shell
uv run tox
```

--------------------------------

### example_function

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

This function demonstrates parameter and return value documentation using reStructuredText.

```APIDOC
## example_function

### Description
This function takes two integer parameters and returns a boolean value. It includes detailed documentation for parameters, return values, and potential exceptions.

### Parameters
#### Path Parameters
- **param1** (int) - Required - The first parameter.
- **param2** (:obj:`str`, optional) - Optional - The second parameter.
#### Query Parameters
- **param1** (int) - Required - The first parameter.
- **param2** (:obj:`str`, optional) - Optional - The second parameter.
#### Request Body
- **param1** (int) - Required - The first parameter.
- **param2** (:obj:`str`, optional) - Optional - The second parameter.

### Request Example
```json
{
  "param1": 10,
  "param2": "example"
}
```

### Response
#### Success Response (200)
- **bool** - True if successful, False otherwise.

#### Response Example
```json
{
  "example": true
}
```

### Raises
- **AttributeError** - 
- **ValueError** - If `param2` is equal to `param1`.
```

--------------------------------

### ExampleClass

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

A sample class with various attributes and methods, documented using NumPy-style docstrings.

```APIDOC
## ExampleClass

### Description
A sample class with various attributes and methods, documented using NumPy-style docstrings.

### Attributes
#### Attributes
- **attr1** (int) - A simple integer attribute.
- **attr2** (str) - A string attribute.
- **attr3** (list) - A list attribute.
- **attr4** (dict) - A dictionary attribute.
- **attr5** (float) - A float attribute.
```

--------------------------------

### NamedTuple Example

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc_py312.html

Shows the definition and usage of a `typing.NamedTuple`.

```APIDOC
## NamedTupleExample

### Description
An example of a `typing.NamedTuple` with fields `name` and `id`.

### Fields
- **name** (str) - The name associated with the NamedTuple.
- **id** (int) - The identifier associated with the NamedTuple.

### Example Usage
```python
class NamedTupleExample(NamedTuple):
    name: str
    id: int

example = NamedTupleExample(name="Example", id=123)
print(example.name, example.id)
```
```

--------------------------------

### demopackage.C.c

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demopackage.txt

The c method from the C class.

```APIDOC
## demopackage.C.c

### Description
This method is inherited from demopackage.child_c.C.

### Method
`c(self)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### alternative_section_names

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

In this example, we use alternative section names.

```APIDOC
## alternative_section_names(test: str)

### Description
In this example, we use alternative section names.

### Parameters
* **test** (str) - Required - 

### Returns
Type not specified.
```

--------------------------------

### DocstringFromNew.__init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

Initializes a new instance of the DocstringFromNew class.

```APIDOC
## DocstringFromNew.__init__

### Description
Constructor for the DocstringFromNew class.

### Parameters
- **param** (type) - Required - Description for param
```

--------------------------------

### Foo.a_static_method

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/demo_long.html

Demonstrates a standard @staticmethod.

```APIDOC
## Foo.a_static_method

### Description
This is what a `@staticmethod` looks like.

### Type
None
```

--------------------------------

### Function with Keyword Arguments

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Demonstrates documenting a function that accepts arbitrary keyword arguments using `**kwargs`.

```python
def keyword_arguments(**kwargs):
    """
    This an example for a function with keyword arguments documented in the docstring.

    Args:
        **kwargs: A dictionary containing user info.

    Keyword Arguments:
        str_arg (str): First string argument.
        int_arg (int): Second integer argument.
    """
    pass
```

--------------------------------

### ExampleError

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.txt

Exceptions are documented using classes.

```APIDOC
## class flavors_numpy.ExampleError

### Description
Exceptions are documented using classes.

### Methods
#### __init__(self, msg, code)
- **msg** (type) - Description
- **code** (type) - Description

#### add_note(self, note: str)
- **note** (str) - Description

#### with_traceback(self, object, /)
- **object** (type) - Description

### Attributes
- **msg** (type)
- **code** (type)
- **args** (type) - inherited from builtins.BaseException.args
```

--------------------------------

### ExampleClass with Various Docstring Styles

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Demonstrates documenting a class, its attributes, and methods using different docstring conventions. Covers inline, before, and after attribute documentation, as well as property documentation.

```python
class ExampleClass(object):
    """The summary line for a class docstring should fit on one line.

    If the class has public attributes, they may be documented here
    in an `Attributes` section and follow the same formatting as a
    function's `Args` section. Alternatively, attributes may be documented
    inline with the attribute's declaration (see __init__ method below).

    Properties created with the `@property` decorator should be documented
    in the property's getter method.

    Attributes
    ----------
    attr1 : str
        Description of `attr1`.
    attr2 : :obj:`int`, optional
        Description of `attr2`.

    """

    def __init__(self, param1, param2, param3):
        """Example of docstring on the __init__ method.

        The __init__ method may be documented in either the class level
        docstring, or as a docstring on the __init__ method itself.

        Either form is acceptable, but the two should not be mixed. Choose one
        convention to document the __init__ method and be consistent with it.

        Note
        ----
        Do not include the `self` parameter in the `Parameters` section.

        Parameters
        ----------
        param1 : str
            Description of `param1`.
        param2 : :obj:`list` of :obj:`str`
            Description of `param2`. Multiple
            lines are supported.
        param3 : :obj:`int`, optional
            Description of `param3`.

        """
        self.attr1 = param1
        self.attr2 = param2
        self.attr3 = param3  #: Doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr4 = ["attr4"]

        self.attr5 = None
        """str: Docstring *after* attribute, with type specified."""

    @property
    def readonly_property(self):
        """str: Properties should be documented in their getter method."""
        return "readonly_property"

    @property
    def readwrite_property(self):
        """:obj:`list` of :obj:`str`: Properties with both a getter and setter

```

--------------------------------

### function_with_pep484_type_annotations

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

Example function with PEP 484 type annotations.

```APIDOC
## function_with_pep484_type_annotations(param1: int, param2: str) -> bool

### Description
Example function with PEP 484 type annotations.

### Parameters
* **param1** (int) - Required - 
* **param2** (str) - Required - 

### Returns
* bool - 
```

--------------------------------

### function_with_pep484_type_annotations

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.txt

Example function with PEP 484 type annotations.

```APIDOC
## function_with_pep484_type_annotations(param1: int, param2: str) -> bool

### Description
Example function with PEP 484 type annotations.

### Parameters
#### Path Parameters
- **param1** (int) - Description
- **param2** (str) - Description

### Returns
- bool: Description
```

--------------------------------

### Documenting Function Parameters and Returns

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.html

Illustrates how to document function parameters, including optional ones and variable arguments, as well as return values and exceptions. Use this for standard function documentation.

```python
def example_function(param1, param2, *args, **kwargs):
    """Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : :obj:`str`, optional
        The second parameter.
    *args
        Variable length argument list.
    **kwargs
        Arbitrary keyword arguments.

    Returns
    -------
    bool
        True if successful, False otherwise.

    Raises
    ------
    AttributeError
        The `Raises` section is a list of all exceptions
        that are relevant to the interface.
    ValueError
        If `param2` is equal to `param1`.

    """
    if param1 == param2:
        raise ValueError('param1 may not be equal to param2')
    return True
```

--------------------------------

### function_with_types_in_docstring

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_numpy.txt

Example function with type information embedded in the docstring.

```APIDOC
## function_with_types_in_docstring(param1, param2)

### Description
Example function with type information embedded in the docstring.

### Parameters
#### Path Parameters
- **param1** (type) - Description
- **param2** (type) - Description
```

--------------------------------

### Initialize SampleClass with likes_spam

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.html

Initializes SampleClass. Use this to set the initial state of whether the class instance likes SPAM.

```python
def __init__(self, likes_spam=False):
    """Inits SampleClass with blah."""
    self.likes_spam = likes_spam
    self.eggs = 0
```

--------------------------------

### ExampleError.add_note

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

This method is present for demonstration purposes.

```APIDOC
## ExampleError.add_note(self, note: str)

### Description
This method is present for demonstration purposes.

### Parameters
* **self**: 
* **note** (str) - Required - 

### Returns
Type not specified.
```

--------------------------------

### function_with_types_in_docstring

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/flavors_google.txt

Example function with type information embedded in the docstring.

```APIDOC
## function_with_types_in_docstring(param1, param2)

### Description
Example function with type information embedded in the docstring.

### Parameters
* **param1**: Type not specified.
* **param2**: Type not specified.

### Returns
Type not specified.
```

--------------------------------

### fun_with_protected_decorator()

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

A function decorated with a name starting with a single underscore.

```APIDOC
## fun_with_protected_decorator()

### Description
A function decorated with a name starting with a single underscore.

### Method
N/A

### Endpoint
N/A
```

--------------------------------

### __init__

Source: https://github.com/mitmproxy/pdoc/blob/main/test/testdata/misc.html

The default initializer for the module or class.

```APIDOC
## __init__

### Description
This is the default initializer.

### Method
POST

### Endpoint
/__init__
```