Include function code and documentation directly in content (via roles, directives, etc)

[choldgraf]

Users often want to directly include the documentation and the raw source from a function, module, etc in their content. This allows them to write their own content before and after, and refer to functions in the same way that they'd like to refer to things like figures.

A design example of how to do this would be a directive like

```{api} modulename.functionname
:kind: function
:source: true
```

Implementation ideas

Sphinx has a few concepts that are similar to this, for example:

Sphinx autofunction, automodule, etc lets you insert functions into documentation with a Directive.

Sphinx autosummary will generate a collection of API docs by specifying a top-level module etc.

The Describing Code tutorial covers a lot of these concepts and is useful for inspiration.

Related issues

• Here's somebody requesting one way to implement this, with literalinclude: literal include directive for function #1884