3

We use Sphinx to document our Flask API. It does a pretty good job, but we are having a problem navigating the documentation it generates.

We document each blueprint separately. Our blueprints are pretty big. Each is about 1000 lines long, and our docstrings are extremely detailed. The result is a Sphinx page which lists endpoints, but with so much intervening documentation between the endpoints that it is very difficult to understand the page. The normal thing to create here would be a table of contents at the top. I believe sphinx autosummary might also be called for here, though I don't know for sure as I have never used it.

Unfortunately autosummary doesn't work, because it doesn't seem to be built to handle the same sort of input as autoflask(sphinxcontrib.autohttp.flask). Does anyone know a way to tell sphinx to create a table of contents which creates within-page links to all the members on the page which is compatible with autoflask?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
melchoir55
  • 6,842
  • 7
  • 60
  • 106

2 Answers2

2

Turns out there is an html file which gets generated in the build folder called http-routingtable.html which does what I'm asking above. Given the purpose of sphinx (documentation) you would think this would be... documented... clearly. Hopefully others experiencing the problem run across this post in the future.

melchoir55
  • 6,842
  • 7
  • 60
  • 106
1

Since v1.5.0 of sphinxcontrib.httpdomain, you can make use of sphinxcontrib.autohttp.flaskqref

Reinbach
  • 761
  • 4
  • 7