flaskqref :order: path violation

Open
  • Is something wrong?
#33 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@ANO3457 is already working on this.

Since Oct 25, 2026.

  • #155 by @ANO3457 — closed without merging
  • #157 by @ANO3457 — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
35/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start with the sphinxcontrib.autohttp.flaskqref directive and reproduce the issue using the index.rst example with :order: path and an endpoint resource. Compare the generated API Summary with the API Details; done means the Summary preserves the path ordering used by the Details section.

Written by the indexing model from the issue text.

Description

bug help wanted

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)
Dominant language
Python
Stars
62
Forks
50
Avg merge
5h 10m
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from sphinx-contrib/httpdomain

All issues in sphinx-contrib/httpdomain

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.