I use this extension with sphinx frequently at work. It's very useful and I find the documentation accurate and verbose.
I recently noticed something (and I believe this has been the case since day 1 of me using this extension). It's not a functional limitation, but purely an aesthetic one.
I use both:
sphinxcontrib.autohttp.flaskqref
sphinxcontrib.autohttp.flask
It generates a nice summary table and an API list.
The index.rst looks like the following
API Summary
-----------
.. qrefflask:: myapp:app
:undoc-static:
:undoc-endpoints: blueprint.endpoint1, blueprint.endpoint2
:order: path
API Details
-----------
.. autoflask:: myapp:app
:undoc-static:
:undoc-endpoints: blueprint.endpoint1, blueprint.endpoint2
:order: path
the rendered output looks like the following (divided by the horizontal ruler)
API Summary
| Resource |
Operation |
Description |
| |
GET /rest |
Serves as an entry-point to implementation |
| Accounts |
GET /rest/v1/accounts |
Shows information about accounts |
| -- |
-- |
-- |
| Root |
GET /rest/v1 |
Shows supported resources and services |
| -- |
-- |
-- |
API Details
GET /rest HTTP/1.1
Serves as an entry-point to implementation
Example Request:
...
Example Response:
...
GET /rest/v1 HTTP/1.1
Shows supported resources and services
Example Request:
...
Example Response:
...
GET /rest/v1/accounts HTTP/1.1
Shows information about accounts
Example Request:
...
Example Response:
...
The examples above are relabeled but the order is maintained from the generated doc. The Details section obeys the :order: directive, but the Summary section violates it.
It appears that if a <resource> (an optional) value is given, flaskqref orders the APIs in a lexicographical order of the resource column rather than the one set by path
Software packages
$ python3 --version
Python 3.5.2
$ pip3 list -vv | grep -i sphinx
Sphinx (3.0.3)
sphinxcontrib-applehelp (1.0.2)
sphinxcontrib-confluencebuilder (1.2.0)
sphinxcontrib-devhelp (1.0.2)
sphinxcontrib-htmlhelp (1.0.3)
sphinxcontrib-httpdomain (1.7.0)
sphinxcontrib-jsmath (1.0.1)
sphinxcontrib-qthelp (1.0.3)
sphinxcontrib-serializinghtml (1.1.4)
I use this extension with sphinx frequently at work. It's very useful and I find the documentation accurate and verbose.
I recently noticed something (and I believe this has been the case since day 1 of me using this extension). It's not a functional limitation, but purely an aesthetic one.
I use both:
It generates a nice summary table and an API list.
The
index.rstlooks like the followingthe rendered output looks like the following (divided by the horizontal ruler)
API Summary
API Details
GET /rest HTTP/1.1
Serves as an entry-point to implementation
Example Request:
...
Example Response:
...
GET /rest/v1 HTTP/1.1
Shows supported resources and services
Example Request:
...
Example Response:
...
GET /rest/v1/accounts HTTP/1.1
Shows information about accounts
Example Request:
...
Example Response:
...
The examples above are relabeled but the order is maintained from the generated doc. The
Detailssection obeys the:order:directive, but theSummarysection violates it.It appears that if a
<resource>(an optional) value is given,flaskqreforders the APIs in a lexicographical order of theresourcecolumn rather than the one set bypathSoftware packages