sphinx-contrib / sphinx-contrib/httpdomain

flaskqref :order: path violation

Open
#33 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug help wanted
Dominant language
Python
Stars
62
Forks
46
Avg merge
1d 11h
Merged PRs (30d)
1

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)

Contributor guide

Open the contributing guide

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.

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.