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

Merged
merged 23 commits into from Mar 6, 2017

Conversation

Projects
None yet
3 participants
@lukasgraf
Member

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 Mar 5, 2017

@tisto tisto added the in progress label Mar 5, 2017

lukasgraf added some commits Mar 5, 2017

Write example requests/responses for docs to separate files
(one for the corresponding request, one for the response).
@datakurre

👍

@tisto

tisto approved these changes Mar 6, 2017

@tisto tisto merged commit 561e066 into master Mar 6, 2017

5 checks passed

Changelog verifier Entry found
Details
Plone Contributors Agreement verifier All users have signed it
Details
code-quality/landscape Code quality remained the same
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details

@tisto tisto deleted the docs-http-examples branch Mar 6, 2017

@tisto tisto removed the in progress label Mar 6, 2017

lukasgraf added a commit that referenced this pull request Mar 7, 2017

lukasgraf added a commit that referenced this pull request Mar 7, 2017

lukasgraf added a commit that referenced this pull request Mar 8, 2017

@erral erral referenced this pull request Mar 10, 2017

Closed

Multilingualism handling #225

3 of 4 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment