Sphinx Autoflask - Differentiate docstrings for GET and POST requests on same function

Question

I have a Flask application I am working on building documentation for via python-sphinx.

I am currently using the autoflask extension from sphinxcontrib.autohttp.flask

My question is : How can I prepare a docstring, which properly applies different information to a GET version and POST version of the same route.

For instance a small function :

@app.route('/add_event', methods=['GET', 'POST'])
def add_event():
    """
    ..http:get:: /add_event
        :return: Test
    ..http:post:: /add_event
        :return: Test2
    """
    if request.method == 'GET':
        # get some things
        person_id = request.args.get('id')
        return render_template('create_event.html', race_event_form=test_form)
    if request.method == 'POST':
        # post some things

        return redirect('/person_profile/id/{0}'.format(request.args.get('id')))

My current extensions in conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinxcontrib.httpdomain',
    'sphinxcontrib.autohttp.flask',
    'sphinxcontrib.autohttp.flaskqref'
]

The sphinx output looks like

Is it possible to right one thing for a GET and another for a POST? Id really like to avoid splitting every function into two separate get / post functions.

Also, is it possible to have autoflask ouput required arguments passed through request.args or request.form like the person_id variable in the GET request ?

Answer 1

Try to remove the overloaded view function from Flask autodoc and define the requests individually, while leaving the rest of your API to be automatically generated.

Here's an example...

In conf.py (order of plugins is important):

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.httpdomain',
    'sphinxcontrib.autohttp.flask',
]

In reStructuredText file:

API
===

.. autoflask:: path.to.your:app
  :undoc-static:
  :undoc-endpoints: your_view_method

.. http:get:: / your_view_endpoint

  Some docstring you wrote.

.. http:post:: / your_view_endpoint

  Another docstring you wrote.
    

With regards to your second question, you might look at the directives for httpdomain here.