Investigate mkdocs

[brandondube]

With any hope, mkdocs' markdown-based core will be better than sphinx and rst. Need to confirm:

• compatible with jupyter notebooks for some parts of docs

• auto-generates API docs based on list of files

• supports numpy-style docstrings

[brandondube]

mkdocstrings can render quite nice docs - see https://github.com/mkdocstrings/mkdocstrings/issues/309

A mechanism to generate the API references on a per-file basis automatically is needed. Unclear if this exists in the open source space yet (see also: pdoc, does it automatically). Would boil down to identifying all def statements that are unindented and all unindented class statements. An AST walker/parser is not even really needed, just lifting identifiers based on a little if line.startswith('def') or line.startswith('class').

[pawamoy]

Take a look at this: https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/gen_doc_stubs.py

The markdown files are automatically generated, one per module, with ::: module instruction in it. You'll need mkdocs-gen-files for this.

[brandondube]

markdown integration not at the level needed for prysm. Sphinx has tools for markdown that should be explored instead, but they may not be able to auto-generate things like TOC. TBC.