pdoc3 currently doesn't generate documentation for instance variables unless they have docstrings. It would be very useful to have a rule that enforced the presence of docstrings for instance variables.

e.g.:

class Test:
    def __init__(self, value):
        self.value = value
        """This is a value."""

We had a function that pydoc documented:

def cfg_get_env(env=os.environ):

Except 'pydoc' did not document 'env=os.environ' but expanded the content of 'os.environ' which is a security issue.

Example:

def method(self):
    """Short description

    @returns: some return val
    """
    pass

Gets converted to:

def method(self):
    """Short description

    Returns:
        s: some return val
    """
    pass

Expected Behavior

A way to include the --http mode's "Python module list" index.html as the root index.html of the --html output.

Actual Behavior

By default, there is no index.html at the top level of the HTML output. There doesn't seem to be a way to enabl

From #82.

Instead of a warning we could simply add a debug log with the path to the used template using its filename attribute, though with the current code each handler must do it.

Also we have no control within the Jinja rendering: when we {% include "template.html" %} we can't even issue a debug log to tell which one was picked up, so I'm not sure about the usefulness of just logging

sphinx.ext.doctest lets you write doctests in your prose documentation (e.g. .rst files), which is really useful for ensuring that usage examples in those docs do in fact still work.

If it's possible to use xdoctest instead of the standard library doctest, that would be lovely - and could do with documentation. If not,

A common-ish mistake for docstring author is to use the label of a parameter as opposed to the actual name. The error message in this scenario could be improved. Right now the parameter docstring is reported as missing. It could be something like "Parameter label (X) is used instead of name (Y)".

When the first version of a function takes some parameters, it generates the right docstring, that we just have to complete.
However, if we change the function by adding/removing parameter(s), and adding/removing a return, the docstring is not automatically updated.
The only solutions I found are:

• either complete by myself, following the format generated
  Problem: must know the format ru

Example:

"""
Args:
    obj: instance of [HelloWorld][1].

Some text.

[1]: https://url.to.helloworld/documentation
"""

This will not work because obj's description is isolated from the rest in the structured data, so the [1] is not available when mkdocstrings renders it, meaning the link will not be rendered.

Maybe we could parse such refs ([1], [link id], e