Consider using Sphinx for gh-pages

[dhermes]

• https://github.com/readthedocs/godocjson
• https://github.com/readthedocs/sphinx-autoapi

[dhermes]

So I went down this rabbit hole and learned quite a bit:

• Installing sphinx-autoapi[go] includes sphinxcontrib-golangdomain which requires Python 2.7
• The only conf.py configuration needed is

  autoapi_type = "go"
  autoapi_dirs = ["..", "../postgres"]

• Actually running sphinx-build invokes godocjson (so it must be available on ${PATH}); however this is just an intermediate that creates some JSON; we have other options for how to get this JSON, e.g. we could just store it as static content in the repo
• To actually get the content to build I had to create "dummy" files docs/index.rst (for Sphinx), docs/contents.rst (for autoapi) and a dummy directory (docs/autoapi/). These happened at different stages of tinkering, so I'm not entirely sure which are truly required.

[dhermes]

It's clear that the sphinx-autoapi project is active (most recent commit was August 17, 2020, i.e. 3 days ago). However, the Go support is not active; the sphinxcontrib-golangdomain project has not had a release since Apr 8, 2018 (after a long hiatus from all other releases in 2013) and has only had 5 commits since 2013.

[dhermes]

I pushed https://github.com/dhermes/golembic/tree/issue-6 to showcase this.

[dhermes]

It'd be nice if I code just specify a custom domain and utilize some kind of shared goodies from the package. I tried autoapi_type = "go-djh" and got

loading pickled environment... done

Extension error:
Invalid autoapi_type setting, following values is allowed: "dotnet", "go", "javascript", "python"
make: *** [Makefile:20: html] Error 2

It's possible that autoapi_generate_api_docs = False could be set and then somehow read directly from JSON from some custom domain (i.e. go-djh).