This contrib extension, sphinxcontrib.httpdomain
, provides a Sphinx
domain for describing HTTP APIs.
You can find the documentation from the following URL:
Documenting RESTful HTTP APIs
Home Page: https://pypi.org/project/sphinxcontrib-httpdomain/
License: Other
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.
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
.
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?
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.
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.
DRF is very popular. It would be a great addition!
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
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
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.
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).
+ sphinx-build -b man -d python-sphinxcontrib-httpdomain doc .
Running Sphinx v4.0.2
Extension error:
Could not import extension sphinxcontrib.autohttp.flask (exception: cannot import name 'force_decode' from 'sphinx.util' (/usr/lib/python3.8/site-packages/sphinx/util/__init__.py))
version
reads 1.8.0
(setup.py
) even in 1.8.1 release
sphinx.locale.get_translation is new from sphinx 1.8.
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.
Could you please push the tag corresponding to the 1.8.1 release? We're using GH archives for Gentoo packaging.
Hi,
could you please consider to drop python 2 code, including dependency on six?
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.
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
Just normal build, install and test cycle used on building package from non-root account:
+ 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 =============================================================================
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?
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!
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:
httpdomain/sphinxcontrib/httpdomain.py
Lines 286 to 291 in 47cee9d
I'm not sure of this is a doc fix or a code fix.
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
It seems like parallel build support was added in #31 . It would be great if this were added into a release
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
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.
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!
It would be great to have support for the Falcon web framework.
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:
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
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
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.
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?
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.
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.
Hi! Could you help me, how localize strings like 'Response JSON Array of Objects'?
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).
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,
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.
It would be great to have support for the Sanic web framework
the setup.py doesn't allow for Python 3.7 nor python 3.8. Please allow the update if it can work.
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)
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)
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 |
-- | -- | -- |
Serves as an entry-point to implementation
Example Request:
...
Example Response:
...
Shows supported resources and services
Example Request:
...
Example Response:
...
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
$ 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)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.