Using Sphinx autodoc to document Flask app

Question

I am having problems in using Sphinx to generate documentation for a Flask app. Without going into specific details of the app its basic structure looks as follows.

__all__ = ['APP']

<python 2 imports>

<flask imports>

<custom imports>

APP = None # module-level variable to store the Flask app

<other module level variables>

# App initialisation
def init():
    global APP

    APP = Flask(__name__)

    <other initialisation code>

try:
    init()
except Exception as e:
    logger.exception(str(e))

@APP.route(os.path.join(<service base url>, <request action>), methods=["POST"])
<request action handler>

if __name__ == '__main__':
    init()
    APP.run(debug=True, host='0.0.0.0', port=5000)

I've installed Sphinx in a venv along with other packages needed for the web service, and the build folder is within a docs subfolder which looks like this

docs
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
├── introduction.rst
└── make.bat

The conf.py was generated by running sphinx-quickstart and it contains the line

autodoc_mock_imports = [<external imports to ignore>]

to ensure that Sphinx will ignore the listed external imports. The index.rst is standard

.. myapp documentation master file, created by
   sphinx-quickstart on Fri Jun 16 12:35:40 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to myapp's documentation!
=============================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   introduction

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

and I've added an introduction.rst page to document the app members

===================
`myapp`
===================

Oasis Flask app that handles keys requests.

myapp.app
---------------------

.. automodule:: myapp.app
   :members:
   :undoc-members:

When I run make html in docs I am getting HTML output in the _build subfolder but I get the following warning

WARNING: /path/to/myapp/docs/introduction.rst:10: (WARNING/2) autodoc: failed to import module u'myapp.app'; the following exception was raised:
Traceback (most recent call last):
  File "/path/to/myapp/venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 657, in import_object
__import__(self.modname)
  File "/path/to/myapp/__init__.py", line 4, in <module>
from .app import APP
  File "/path/to/myapp/app.py", line 139, in <module>
@APP.route(os.path.join(<service base url>, <request action>), methods=['GET'])
  File "/path/to/myapp/venv/lib/python2.7/posixpath.py", line 70, in join
elif path == '' or path.endswith('/'):
AttributeError: 'NoneType' object has no attribute 'endswith'

and I am not seeing the documentation I am expecting to see for the app members like the request handler and the app init method.

I don't know what the problem is, any help would be appreciated.

Answer 1

Try using sphinx-apidoc to automatically generate Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools. You will need to add 'sphinx.ext.autodoc' to your list of Sphinx extensions in your conf.py, too.