Just spent the last two weeks (no exaggeration) putting documentation together. Ensuring references resolve correctly is the time consuming bit.

extlinks, nitpick_ignore, autodoc_type_aliases, intersphinx_mapping, multiple extensions, and building inventories using sphobjinv, Table of contents using sphinx-external-toc-strict links to both ref and docs.

The table of contents supports both .md and .rst files. With the caveat that the initial file must be index.rst.

Having to relearn all this crap to do the same thing (e.g. mkdocs)? Would rather stick a fork in my eye.

Here is a sample TOC config file wreck _toc.yml from package wreck. Shows globs:, file:, url: links.

This one includes both .rst and .md strict TOC _toc.yml

Output is a user manual web site or a pdf.

markdown and restructuredText are input files, not the end goal.

Would seriously love someone to rip down Sphinxdoc and put this baby to bed.

In my history of using docstrings, I've put maybe 20-40minutes of docs into a 200k+ codebase. It's super easy.

In my history of using Sphinx autodoc, I've spent about 5-10 hours fumbling with Makefiles, configs, and other nightmares and it still has the worst developer experience after about 8 years of using it.