Long term planning.

As a first pass, I'd like to get the following relatively stable / working before making a wide announcement / adoption.

1) The gen part should be relatively stable and working well in a defined subset of the scipy stack, we are not trying to replace sphinx, and the focus – for now, should be on being able to better rendering, crosslink of docstrings, grouped by projects (and versions of some project). (re) build multiple versions of Numpy, Scipy... to see how it looks like. The gen part is the most important as once done projects with _rarely_ regen their docs.

2) The configuration should be fairly minimal if not necessary, and try to work out of the box. If it helps it would be great to standardize across project. Some information is critical to get _now_ even if not understood yet by the rest of the stack but that can still be done later. For example:

- GitHub repo slug,
- Release commit hash
- function file and line.
- Aliasing fully-qualified name, reference name.
- link to narative docs.
- logo
- authors,

3) Support of images, math and other _simple_ directive and rst features

4) Something like the IPython directive that _does_ execute code and embed result, store whether the code has been execute/checked by this directive and store in an attribute. I'm thinking something like rustdocs that marks in red/yellow example that _might_ be invalid.

5) proper inference working across examples.

6) Segregate backreference from which section they come from (examples generate way too many references, and if something is explicitly referenced it should have higher priority).

7) draft integration into IPython (ascii rendering), spyder, jupyterlab, xonsh.

No source file, test, or entry point is named. Treat this as a roadmap rather than a self-contained task: first confirm which goal is in scope with maintainers, then define acceptance criteria for that goal before implementation.

Written by the indexing model from the issue text.