Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Use sphinxcontrib-httpexample and convert existing examples #248

Merged
merged 23 commits into from
Mar 6, 2017

Conversation

lukasgraf
Copy link
Member

@lukasgraf lukasgraf commented Mar 5, 2017

Use sphinxcontrib-httpexample and convert existing examples in documentation to use the new directive.

Example Docs Build

Also

  • Write example requests/responses to separate files
  • Add HTTP/1.1 to the request/response line in order to make examples valid HTTP
  • Dump request body (if there is one) to example files
  • Include Content-Type header for requests that have a body
  • Include Authorization header when dumping requests

TODO (in follow-up PRs):

  • Some examples still use literal sphinxcontrib-osexample base example requests. These didn't have a corresponding file in docs/source/_json that could be used with sphinxcontrib-httpexample, so those will need to be produced using a "test" in test_documentation.py first, and then converted
  • Rename the folder with dumped requests/responses from _json to something more meaningful (_httpexamples?)
  • When dumping request bodies, the JSON contained in them should be pretty printed beforehand

@lukasgraf lukasgraf requested review from datakurre and tisto March 5, 2017 16:00
(one for the corresponding request, one for the response).
@lukasgraf lukasgraf force-pushed the docs-http-examples branch 2 times, most recently from 6df7f70 to 5642255 Compare March 5, 2017 17:21
@lukasgraf lukasgraf force-pushed the docs-http-examples branch from df63732 to 72151a7 Compare March 5, 2017 17:32
Copy link
Member

@datakurre datakurre left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@tisto tisto merged commit 561e066 into master Mar 6, 2017
@tisto tisto deleted the docs-http-examples branch March 6, 2017 13:33
@tisto tisto removed the in progress label Mar 6, 2017
@erral erral mentioned this pull request Mar 10, 2017
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants