flaskqref :order: path violation #33
Description
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)