Hi,

today I tried to update to sphinx 4.0.0 and the build of doc failed on:

Extension error:
Could not import extension sphinxcontrib.autohttp.flask (exception: cannot import name 'force_decode' from 'sphinx.util' (/var/home/zlopez/git/anitya/.tox/docs/lib/python3.9/site-packages/sphinx/util/__init__.py))

It seems that force_decode is deprecated from Sphinx 2.0 and it is removed completely in 4.0. See https://www.sphinx-doc.org/en/master/extdev/deprecated.html

When building with -j auto a duplicate warning is thrown about the same file when nothing is actually duplicated

afaict it throws the warning for every invokation of httpdomain in our docs

typical warnings from our ci logs:

WARNING: duplicate HTTP post method definition /reopen_logs in /source/generated/rst/operations/admin.rst, other instance is in /source/generated/rst/operations/admin.rst
WARNING: duplicate HTTP get method definition / in /source/generated/rst/operations/admin.rst, other instance is in /source/generated/rst/operations/admin.rst
WARNING: duplicate HTTP get method definition /help in /source/generated/rst/operations/admin.rst, other instance is in /source/generated/rst/operations/admin.rst
WARNING: duplicate HTTP get method definition /certs in /source/generated/rst/operations/admin.rst, other instance is in /source/generated/rst/operations/admin.rst

not sure if just preventing the warning when both sources are the same would work (or whether that would actually suppress real duplicates)

if this is a reasonable fix im happy to pr

Haven't found any other discussion on this:

I am running this extension as from scripts inside a docker container.

The installer recognizes sphinxcontrib vs for example sphinx-contrib but doesn't recognize sphinx.httpdomain.

Just normal build, install and test cycle used on building package from non-root account:

• "setup.py build"
• "setup.py install --root </install/prefix>"
• "pytest with PYTHONPATH pointing to setearch and sitelib inside </install/prefix>

+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILDROOT/python-sphinxcontrib-httpdomain-1.7.0-13.fc35.x86_64/usr/lib64/python3.8/site-packages:/home/tkloczko/rpmbuild/BUILDROOT/python-sphinxcontrib-httpdomain-1.7.0-13.fc35.x86_64/usr/lib/python3.8/site-packages
+ PYTHONDONTWRITEBYTECODE=1
+ /usr/bin/pytest -ra
=========================================================================== test session starts ============================================================================
platform linux -- Python 3.8.9, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
benchmark: 3.4.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /home/tkloczko/rpmbuild/BUILD/httpdomain-1.7.0
plugins: forked-1.3.0, shutil-1.7.0, virtualenv-1.7.0, expect-1.1.0, httpbin-1.0.0, flake8-1.0.7, timeout-1.4.2, betamax-0.8.1, freezegun-0.4.2, case-1.5.3, isort-1.3.0, aspectlib-1.5.2, asyncio-0.15.1, toolbox-0.5, xprocess-0.17.1, aiohttp-0.3.0, checkdocs-2.7.0, mock-3.6.1, rerunfailures-9.1.1, requests-mock-1.9.3, cov-2.12.1, pyfakefs-4.5.0, cases-3.6.1, flaky-3.7.0, hypothesis-6.14.0, benchmark-3.4.1, xdist-2.3.0, pylama-7.7.1, Faker-8.8.2, datadir-1.3.1, regressions-2.2.0
collected 2 items / 1 error / 1 selected

================================================================================== ERRORS ==================================================================================
___________________________________________________________________ ERROR collecting test/bottle_test.py ___________________________________________________________________
ImportError while importing test module '/home/tkloczko/rpmbuild/BUILD/httpdomain-1.7.0/test/bottle_test.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/lib64/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
test/bottle_test.py:3: in <module>
    from sphinxcontrib.autohttp.bottle import get_routes
/usr/lib/python3.8/site-packages/sphinxcontrib/autohttp/bottle.py:20: in <module>
    from sphinx.util import force_decode
E   ImportError: cannot import name 'force_decode' from 'sphinx.util' (/usr/lib/python3.8/site-packages/sphinx/util/__init__.py)
========================================================================= short test summary info ==========================================================================
ERROR test/bottle_test.py
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
============================================================================= 1 error in 0.38s =============================================================================

The documenation states that the following are appropriate for documenting a request/response header:

requestheader, reqheader, >header
responseheader, resheader, <header

The code diverges from this:

I'm not sure of this is a doc fix or a code fix.

version reads 1.8.0 (setup.py ) even in 1.8.1 release

This package requires tornado 4. However, tornado 4 will stop working with Python 3.8. Tornado 5 was released March 2018 and Tornado 6 was release March 2019. Both will work with Python 3.8. Would it be possible to update this package to work with at least tornado 5 and ideally both tornado 5 and 6 so it can be used with Python 3.8? Thank you.

Commit 81ab0e0 fixed https://bitbucket.org/birkenfeld/sphinx-contrib/pull-requests/152/fix-182-by-moving-around-initialization/diff, which is a release breaking bug preventing the use of autohttp.flask
A release with this fix would be much apprectiated.

Hi,

maybe it's a mis usage from my side, but I can't get httpdoamain to properly work with intersphinx.

The issue I have is if I put an intersphinx reference to a httpdomain node without making it explicit, the WARNING: Cannot resolve reference message is triggered (even if the reference resolution actually worked ok).

This is annoying since we do run sphinx with -W in our CI, and currently we are hacking the build system inserting a custom log filter to prevent these messages to generate an error (because of the -W), and I'd like to get rid of this hack.

I've attached a minimal project to reproduce the issue.

The useful part of the index.rst file is

This is ok: :external:http:get:`/api/1/resolve/(swhid)/`.
This is not: :http:get:`/api/1/resolve/(swhid)/`.

Building the doc from there, you should see:

test-httpdomain$ make html
Running Sphinx v7.2.6
making output directory... done
loading intersphinx inventory from https://docs.softwareheritage.org/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
/home/ddouard/tmp/test-httpdomain/index.rst:9: WARNING: Cannot resolve reference to <#text: 'GET /api/1/resolve/(swhid)/'>
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in _build/html.

Notice the WARNING being generated for the non-explicit external reference.

yt_dl-2020.9.20.tar.gz

It would be great to have support for the Falcon web framework.

I'm trying to get a Framework :: Sphinx :: Domain PyPi classifier approved to help with the Sphinx docs as well as keep the ecosystem more organize and I need to demonstrate interest by having 10 or more project maintainers submit comments about their desire to use the new classifier.

If the maintainer of this project thinks a Framework :: Sphinx :: Domain would be useful for helping people find the domain as well as help the greater Sphinx ecosystem, please leave a comment on sphinx-doc/sphinx#11562 expressing interest in using the classifier with a link to the package that you maintain to help with the approval process.

Once it gets approved I can come back and submit a PR to add it to the package metadata.

Thanks!

The request should look as follows:

curl -i -X POST https://api.compile.com/v21/encrypted_flies -H 'Accept: application/vnd.api+json' -H 'Api-Key: [API token]' -H 'Content-Type: multipart/form-data' --form 'Encrypted_flies[encryption_fingerprint]: c24c8711fed0fb9df377d4dad6090038063eec27:::d8919eb961da809e4d597f5c072e04383055e219' --form 'Encrypted_flies[items][][description]: my file

the best I can achieve is "Raw data" for both encrypted flies items for e.g.

--data-raw ':form body: encrypted_files[items][][description]:my file

Hi! Could you help me, how localize strings like 'Response JSON Array of Objects'?

Indices and tables
==================

* :ref:`routingtable`
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

On a clean build produces:

.../docs/index.rst:28: WARNING: undefined label: routingtable

Specifically with the command sphinx-build -j auto -n $SRC/docs $SRC/docs/_build/html.

Recent versions of Sphinx have removed the Directive class from sphinx.util.compat, trying to import the autohttp.flask extension produces this error:

sphinx-build -b html -E -T source build
Running Sphinx v1.7.1

Traceback (most recent call last):
  File "/usr/lib64/python2.7/site-packages/sphinx/cmdline.py", line 303, in main
    args.warningiserror, args.tags, args.verbosity, args.jobs)
  File "/usr/lib64/python2.7/site-packages/sphinx/application.py", line 191, in __init__
    self.setup_extension(extension)
  File "/usr/lib64/python2.7/site-packages/sphinx/application.py", line 411, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib64/python2.7/site-packages/sphinx/registry.py", line 318, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname, err)
ExtensionError: Could not import extension sphinxcontrib.autohttp.flask (exception: cannot import name Directive)

This works with Sphinx v.1.6.1.

As an HTTP API docs writer,
I want to have web-socket resource .rst directives,
So I can doc a web-socket resource endpoint, just like I doc HTTP resource endpoint.

As of today, doc of web-socket API resource endpoints is not out-of-the-box of this extension.

For HTTP APIs, there is a possibility to have web-socket resource endpoints (additional to the HTTP resource endpoints).

Suggested directives syntax:

.. http:ws:: <url>

:server-event <event-name>:
:client-event <event-name>:

Example, for a web-socket API endpoint (in the light of the this extension official docs):

.. http:ws:: /users/(int:user_id)/posts/

   Returns a post that the user (`user_id`) just added.

   :reqheader cookie:
   :server-event add:

   **Example response**:

   .. sourcecode:: json

        {
          "post_id": 54321,
          "author_id": 123,
          "tags": ["server", "web"],
          "subject": "Tomcat doesn't work"
        }

   :statuscode 401: user is not authorized.

Might be rendered to:

DRF is very popular. It would be a great addition!

https://www.django-rest-framework.org/

the setup.py doesn't allow for Python 3.7 nor python 3.8. Please allow the update if it can work.

I'm using httdomain on a tornado project with "auto tornado" to generate API documentation and it's great. A nice-to-have feature is the ability to specify a custom filter function to the autotornado directive to allow for greater dynamic control over which API routes are published vs. not. A few use cases include:

• Private/internal APIs endpoints that shouldn't be accessed by end-users
• "Unstable" APIs that are intended for eventual public consumption but should remain undocumented in official docs until the API has stabilized

I'd propose a "filter-endpoints" parameter to the auto tornado directive. It would take a tornado rule target (Rule or URLSpec) or a method/function target of such rule and return True to exclude the item (the item is filtered) and False to include it (the item is not filtered).

For instance, a filter function that excludes classes and methods which have "PRIVATE API" in the docstring:

def doctoring_private_filter(obj):
    return "PRIVATE API" in obj.__doc__

And would be setup as:

    .. autotornado:: yourwebapp:app
        :filter-endpoints: yourwebapp:docstring_private_filter

Getting this error when running make html using python3.6.5

Extension error: Could not import extension sphinxcontrib.httpdomain (exception: No module named 'sphinxcontrib.httpdomain') Makefile:20: recipe for target 'html' failed make: *** [html] Error 2

When clicking on a link generated by a :statuscode: directive, it leads to a document marked as superseded; as an example, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1. Can the link be fixed, or can the status link be entirely disabled using some configuration entry for the extension?

It seems like parallel build support was added in #31 . It would be great if this were added into a release

Wondering if it could be possible to register a potion ModelResource with sphinxcontrib.httpdomain?
Unless I overload all possible routes and register that in the endpoints directive, is there another way?

Hi,
could you please consider to drop python 2 code, including dependency on six?

Hey!

First things first. Thanks for your awesome work 😎

I was wondering if there would one day eventually be a possibility for users to add custom colors for the different request types, for example: red for DELETE, etc.

Thanks in advance

auto tornado assumes "handler_class" and "regex" properties on the "spec" objects, consistent with the URLSpec object. However, in Tornado 4.5, routes may be rules (and URLSpec is a subclass of rule), and rules have "target" and "matcher" properties (with regex @ matcher.regex).

Since I recently have no much chance to use Python at all, it's getting less motivating me to maintain this project. If someone who wish maintain this project from now on, I would like to give them all necessary accesses (this repository, PyPI, & RTD.org). No special prerequisites, but it would be great if them have experience of developing any Sphinx extensions or sending patches to this project.

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

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)

It would be great to have support for the Sanic web framework

Hey!
I have a problem with my sphinx-generated PDF documents. sphinxcontrib.httpdomain makes an index (http routing table) for all pdf-docs even if there is not HTTP API in current file (but i is in other documentaton parts).
May be it will be good to add a flag to enable/disable making index?

my object structure ：

{
"name":"Mick",
"att":{
    "url" :"www.domain.com",
   "other" :{
         "desc":"hello world"
     }
  }
}

I want to show it as follows：

Response Json Object:

• name :
• att :
  • other :
    • desc :

Hope to get your help , thanks!

sphinx.locale.get_translation is new from sphinx 1.8.

I have a proof of concept pull request in with sphinx_rtd_theme at the moment to add functionality to both colour rendered HTTP endpoint banners differently per HTTP method and to make the endpoint sections collapsible (readthedocs/sphinx_rtd_theme#796). A screenshot gif of what this looks like is included in that pull request.

It has been suggested that the javascript parts of that pull request possibly make more sense to put into this package, because it might have use in other themes as well. Another option is to make those changes a totally standalone package.
So this issue is to discuss what you think would work best (or at least highlight that pull request so that you can add your thoughts there).

Could you please push the tag corresponding to the 1.8.1 release? We're using GH archives for Gentoo packaging.

If a resource is documented as:

.. http:get:: /myresource

  This is a resource.

It can be referenced by :http:get:`/myresource` , which turns into a clickable link.

However, I do not want my PDF to contain a routing table. So I add :noindex to the directive.
Now the role no longer produces a clickable link and Sphinx logs a warning WARNING: Cannot resolve reference to <#text: 'GET /myresource'>.

Is there a way to make a resource not appear in the routing table in a way that the role can still link to the directive?

When using sphinx-build -j auto:

the sphinxcontrib.httpdomain extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

In the latest update to werkzeug they deleted parse_rule. This breaks autoflask.
So for anyone running into issues with their doc generation with flask they should pin their dependencies to an earlier version.

I hit a problem in combination with newer sphinx (in my case 4.2.0):

This example was previously (3.5.4) working just fine:

.. http:get:: /test

   Some Text

   :query string sort: query parameter description

But with the newer Sphinx emits a warning (and thus breaks strict builds):

/home/hofmandl/sphinx-http/index.rst:5: WARNING: Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.

According to https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/#resource-fields specifying a type is a perfectly valid usecase for the query-option.

When changing to :query sort: query parameter description the warning goes away.

It seems like with the release of Sphinx v2.1.1, this domain's use of typed fields isn't really working any more in documentation where more than one domain gets used in the documentation.

Please see issue 6478 on Sphinx itself; I believe the defect lies in a refactoring that happened there, and not really here. A workaround fix for this domain package is to insert a _doc_field_type_map = {} class variable declaration inside the HTTPResource class definition, I think.

When referencing status code 200 with tools like https://github.com/sphinx-contrib/openapi the reference is passed to a superseeded document:

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1

Could this be updated?

This is the reference issue in sphinx-contrib/openapi:
sphinx-contrib/openapi#157 (comment)

Hi,

When an endpoint is marked with dual methods, two docstrings are generated. Additionally, a given form parameter will show up in both GET and POST though it is only applicable for the latter.

See also:
https://stackoverflow.com/questions/40744982/sphinx-autoflask-differentiate-docstrings-for-get-and-post-requests-on-same-fu

Hi,

I recently started getting this error when building sphinx documentation. You can see the log from the build here.

The sphinx config can be found here

And the whole docs is here

The autoflask usage is only in this rst file

I'm not sure how to fix this issue, because it doesn't seem to refer to anything in the documentation itself.