pythonpyramidpython-sphinxdocumentation-generationcornice

Documenting Cornice's Resources with Cornice's Sphinx integration


I have a Pyramid application with Cornice package where I defined Resources (rather than Services) and I wonder if it is possible to generate Sphinx documentation for this project with a help of Cornice's Sphinx integration?

I managed to generate some sort of documentation but it seems like majority of features are not available for Resources, only for Services, for example, documenting Pyramid code in this way:

@resource(collection_path='/parse/', path='/parse/{id}', cors_origins=('*',), description="Temporary description.")
class Parser(object):

    @view(renderer='json')
    def collection_post(self):
        """
        Some description for this function...
        :param str smth: Some parameter
        :return: Returns something
        """
        return

and building Sphinx documentation like this:

.. cornice-autodoc::
   :modules: my_app.views.views_parser
   :ignore: parser

will result in few unnecessary and few missing parts in documentation:


(example snippet from generated documentation)

Collection_Parser service at /parse/

Temporary description.

POST

Response: json

Parser service at /parse/{id}

Temporary description.


What I would like to know is:

...and many other things...
It seems like this is either impossible or not documented at all. If the case is that this is impossible is there any other (at least semi-automated) solution for documenting my project?


Solution

  • Seems like this is not possible because Cornice does not support this kind of functionality (https://github.com/mozilla-services/cornice/issues/279)...