Setup documentation framework

[goodmami]

I'm undecided if we should use Sphinx, MkDocs, or even plain Markdown rendered by GitHub (example).

[goodmami]

Sphinx seems a bit dated and somehow feels heavy, so I wanted to try a fresher alternative. I attempted MkDocs and here's what I found:

• Setup was easy
• Themes are beautiful and customizing is relatively easy
• Using Markdown is generally nice
• The built-in server and live-update feature is really nice when writing
• Autoapi support is spotty; there are many solutions, a few of them actively developed, but they are very limiting
  • The most popular, mkdocstrings, won't display the function signature for me (though it seems to get the docstring just fine)
  • mkdocstrings also gets the absolute import path instead of the public API version; e.g., I tell it to document wn.synset and it generates references to wn._core.synset
  • The second most popular, MkAutoDoc displays the function signatures using the public API, but it doesn't help with module docstrings, type annotations, or google/numpy style docstrings
• There's no regular API directives (like ReST's .. function:: foo(bar)) that I could find
• There doesn't seem to be anything like intersphinx
• MkDocs seems to have some obsession with using the One True Gruberian Markdown (through python-markdown), plus extensions, instead of Commonmark, plus extensions. Basically this means that it's more annoying to write nested lists.

In the end, I can get nice docs with MkDocs, but I'd have to either hand-format all my API entries (e.g., function signatures), which is basically the "plain Markdown" option, or I'd have to hack on some of the auto-api solutions to get them working.

Searching the web for "mkdocs vs sphinx" also turned up this issue, which has some additional thoughts

So it looks like I'll stick with Sphinx. On the plus side, there's a Material theme for Sphinx and some nice options for editing with Markdown instead of ReST (see the first comment in the linked issue), and Sphinx is being actively developed, so not only is it more mature but it'll probably keep improving.

[goodmami]

While I haven't tried it yet, the Material theme may have issues being deployed on ReadTheDocs. There's also pradyunsg's new furo theme which also looks pretty good.

[goodmami]

Sphinx is now building with a GitHub action and deploying to https://goodmami.github.io/wn, so I think this can be closed, although at some point I may want to host at ReadTheDocs.