Why sphinxcontib-httpdomain directive http:post is unknown? - python-sphinx

Question

I have trouble with sphinxcontrib-httpdomain. If i defining http get or post or any another domain, sphinx-build tells me about error
Unknown directive type "http:get"
Definition of http:post domain in my sources:
.. http:get:: /users/(int:user_id)/posts/(tag)
The posts tagged with `tag` that the user (`user_id`) wrote.
**Example request**:
.. sourcecode:: http
GET /users/123/posts/web HTTP/1.1
Host: example.com
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
[
{
"post_id": 12345,
"author_id": 123,
"tags": ["server", "web"],
"subject": "I tried Nginx"
},
{
"post_id": 12346,
"author_id": 123,
"tags": ["html5", "standards", "web"],
"subject": "We go to HTML 5"
}
]
:query sort: one of ``hit``, ``created-at``
:query offset: offset number. default is 0
:query limit: limit number. default is 30
:reqheader Accept: the response content type depends on
:mailheader:`Accept` header
:reqheader Authorization: optional OAuth token to authenticate
:resheader Content-Type: this depends on :mailheader:`Accept`
header of request
:statuscode 200: no error
:statuscode 404: there's no user
There are two blank lines before and after this block. I tried to use 3,4 spaces and to offset contents of block
Contents of extensions block of conf.py:
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.extlinks',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.ifconfig',
'sphinx.ext.doctest',
'sphinx.ext.graphviz',
'sphinxcontrib.httpdomain'
]
What i'd tried also and it doesn't helped:
- To reinstall all sphinx* packages via pip
To reinstall all sphinx* packages via apt-get
To specify path to extension in conf.py
To reinstall all autodoc, docutils packages via pip
To build on another host (same error)
To look at build logs with -vvv mode
To read [official plugin docs][3] and do all of steps
Some information which can be useful:
All packages are installed to /usr/local/lib/python2.7/dist-packages
pip show sphinx output:
Name: Sphinx
Version: 1.6.7
Summary: Python documentation generator
Home-page: http://sphinx-doc.org/
Author: Georg Brandl
Author-email: georg#python.org
License: BSD
Location: /usr/local/lib/python2.7/dist-packages
Requires: sphinxcontrib-websupport, babel, imagesize, setuptools, typing, Pygments, requests, six, docutils, alabaster, Jinja2, snowballstemmer
pip show sphinxcontrib-httpdomain output:
Name: sphinxcontrib-httpdomain
Version: 1.6.0
Summary: Sphinx domain for documenting HTTP APIs
Home-page: https://github.com/sphinx-contrib/httpdomain
Author: Hong Minhee
Author-email: hong.minhee#gmail.com
License: BSD
Location: /usr/local/lib/python2.7/dist-packages
Requires: six, Sphinx
uname output:
Linux 4.13.0-32-generic #35-Ubuntu SMP Thu Jan 25 09:13:46 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux

Answer 1

After fighting with this problem for a while, I finally found the solution. The version included in Debian buster and Ubuntu bionic (and newer) has a patch added which solved an issue, but added this problem.
The patch comes from this commit, but it is missing the fix added a couple of days after in this other commit.
It seems that even if you tried to install with pip, you were using the system version. You can patch it trivially by editing the code at /usr/lib/python2/dist-packages/sphinxcontrib/httpdomain.py.
I am sending the patch to the package maintainer so it hopefully will be fixed soon in unstable.