Make HTTP calls in docs more readable (and maybe testable)

[tisto]

Writing docs for plone.restapi is currently a pain. Say I want to write down an example for sending a POST request with some payload:

    POST /folder HTTP/1.1
    Host: localhost:8080
    Accept: application/json
    Content-Type: application/json

    {
        '@type': 'Document',
        'title': 'My Document',
    }

What I have to actually write is this:

.. example-code::

  .. code-block:: http-request

    POST /folder HTTP/1.1
    Host: localhost:8080
    Accept: application/json
    Content-Type: application/json

    {
        '@type': 'Document',
        'title': 'My Document',
    }

  .. code-block:: curl

    curl -i -H "Accept: application/json" -H "Content-type: application/json" --data-raw '{"@type":"Document", "title": "My Document"}' --user admin:admin -X POST http://localhost:8080/Plone/folder

  .. code-block:: httpie

    http -a admin:admin POST http://localhost:8080/Plone/folder \\@type=Document title=My Document Accept:application/json

  .. code-block:: python-requests

    requests.post('http://localhost:8080/Plone/folder', auth=('admin', 'admin'), headers={'Accept': 'application/json'}, json={'@type': 'Document', 'title': 'My Document'})

This is not only a lot of work to write, but also error prone. This approach will also not scale if we want to include more options. I guess it should be possible to auto-generate the curl, httpie, or python-requests examples from the initial pseudo-code HTTP request. Thanks to @svx we already have a library that renders the latter. I'm wondering if we could write a sphinx library that makes writing plone.restapi docs fun again. If we have such a library, we might be able to make the examples testable as well (doctests on speed).

@datakurre you have some experience with writing sphinx docs extensions. what do you think, is that doable?

[datakurre]

I believe that auto-generating is possible, but I'm not sure how well it will work with testing (if we generate code which we then test, debugging might become harder).

…

On 15. helmikuuta 2017 klo 17.56 +0200, Timo Stollenwerk ***@***.***>, wrote: Writing docs for plone.restapi is currently a pain. Say I want to write down an example for sending a POST request with some payload: POST /folder HTTP/1.1 Host: localhost:8080 Accept: application/json Content-Type: application/json { ***@***.***': 'Document', 'title': 'My Document', } What I have to actually write is this: .. example-code:: .. code-block:: http-request POST /folder HTTP/1.1 Host: localhost:8080 Accept: application/json Content-Type: application/json { ***@***.***': 'Document', 'title': 'My Document', } .. code-block:: curl curl -i -H "Accept: application/json" -H "Content-type: application/json" --data-raw ***@***.***":"Document", "title": "My Document"}' --user admin:admin -X POST http://localhost:8080/Plone/folder .. code-block:: httpie http -a admin:admin POST http://localhost:8080/Plone/folder ***@***.***=Document title=My Document Accept:application/json .. code-block:: python-requests requests.post('http://localhost:8080/Plone/folder', auth=('admin', 'admin'), headers={'Accept': 'application/json'}, ***@***.***': 'Document', 'title': 'My Document'}) This is not only a lot of work to write, but also error prone. This approach will also not scale if we want to include more options. I guess it should be possible to auto-generate the curl, httpie, or python-requests examples from the initial pseudo-code HTTP request. Thanks to @svx (https://github.com/svx) we already have a library that renders the latter. I'm wondering if we could write a sphinx library that makes writing plone.restapi docs fun again. If we have such a library, we might be able to make the examples testable as well (doctests on speed). @datakurre (https://github.com/datakurre) you have some experience with writing sphinx docs extensions. what do you think, is that doable? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub (#196), or mute the thread (https://github.com/notifications/unsubscribe-auth/AAJyv11qJrzQMPphMfVYdL2kCx_1bc-4ks5rcyAOgaJpZM4MB4-r).

[lukasgraf]

I agree, this bothers me as well. Not only is it cumbersome to write those examples by hand, but the URLs used in them also differ from test_documentation.py generated snippets (http://localhost:55001/plone vs. http://localhost:8080/Plone), as does the assumed content structure.

All this ties into acceptance testing and keepingplone.server in sync as well (see #162 / #137).

I don't have time to look at this in depth right now (swamped in work), but I'm very interested in working in this, possibly at the sprint.

[datakurre]

Would it be ok to have original pseudo-examples in docs inline and generate both documentation examples and tests from those? Or something else? I could work on the Sphinx plugin during the sprint. Anything should be possible :)

[tisto]

@datakurre I would say ideally we would generate the real world examples from our pseudo-examples. The docs writer would just write the pseudo calls and the sphinx extension would auto-generate the real-world examples from this. Maybe it is sufficient if we test our sphinx extension properly.

[datakurre]

@lukasgraf Are you still interested in working with this with me on the sprint?

I'm planning an independent Sphinx-plugin (at least one new package), which could

• parse pseudo examples and generate real examples
• has new directive to replace pseudo examples with generated examples in Sphinx code
• has test utility to collect examples as executable tests with configurable test fixture (pytest, plone.testing)

It should be possible to work with any of these independently.

@tisto What kind of tests would you like to be generated from the pseudo code? Just python-test using requests-library or should the tests use the tools in generated examples? Or both? Which one is the priority?

@tisto Do you already have more pseudo-examples (in addition to the one in this ticket) available somewhere?

[datakurre]

https://pypi.python.org/pypi/sphinxcontrib-httpexample

[tisto]

Wohoo! (sorry for doing this over and over again).