Sphinx: Sphinx 1.4.5 fails to build API documentation for a Flask application

Created on 19 Jul 2016 · 3Comments · Source: sphinx-doc/sphinx

I have a Flask web application for which I build the documentation with Sphinx. Up to version 1.4.4 this worked fine but in 1.4.5 I suddenly run into a Runtime error. sphinx-apidoc runs fine but when I try make html, I get this output:

sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.4.5
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 93 source files that are out of date
updating environment: 93 added, 0 changed, 0 removed
reading sources... [  1%] apidoc/hmi                                                                    
Exception occurred:
  File "/usr/local/lib/python3.4/dist-packages/flask/globals.py", line 44, in _lookup_app_object
    raise RuntimeError(_app_ctx_err_msg)
RuntimeError: Working outside of application context.

This typically means that you attempted to use functionality that needed
to interface with the current application object in a way.  To solve
this set up an application context with app.app_context().  See the
documentation for more information.
The full traceback has been saved in /tmp/sphinx-err-m4doq5p5.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 1

This is the traceback from the error log:

# Sphinx version: 1.4.5
# Python version: 3.4.3 (CPython)
# Docutils version: 0.12 release
# Jinja2 version: 2.8
# Last messages:
#   Running Sphinx v1.4.5
#   loading pickled environment...
#   not yet created
#   building [mo]: targets for 0 po files that are out of date
#   building [html]: targets for 93 source files that are out of date
#   updating environment:
#   93 added, 0 changed, 0 removed
#   reading sources... [  1%] apidoc/hmi
# Loaded extensions:
#   sphinx.ext.coverage (1.4.5) from /usr/local/lib/python3.4/dist-packages/sphinx/ext/coverage.py
#   sphinx.ext.viewcode (1.4.5) from /usr/local/lib/python3.4/dist-packages/sphinx/ext/viewcode.py
#   sphinx.ext.autodoc (1.4.5) from /usr/local/lib/python3.4/dist-packages/sphinx/ext/autodoc.py
#   alabaster (0.7.8) from /usr/local/lib/python3.4/dist-packages/alabaster/__init__.py
Traceback (most recent call last):
  File "/usr/local/lib/python3.4/dist-packages/sphinx/util/inspect.py", line 109, in safe_getattr
    return getattr(obj, name, *defargs)
  File "/usr/local/lib/python3.4/dist-packages/werkzeug/local.py", line 343, in __getattr__
    return getattr(self._get_current_object(), name)
  File "/usr/local/lib/python3.4/dist-packages/werkzeug/local.py", line 302, in _get_current_object
    return self.__local()
  File "/usr/local/lib/python3.4/dist-packages/flask/globals.py", line 44, in _lookup_app_object
    raise RuntimeError(_app_ctx_err_msg)
RuntimeError: Working outside of application context.

This typically means that you attempted to use functionality that needed
to interface with the current application object in a way.  To solve
this set up an application context with app.app_context().  See the
documentation for more information.

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/local/lib/python3.4/dist-packages/sphinx/cmdline.py", line 244, in main
    app.build(opts.force_all, filenames)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/application.py", line 297, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.4/dist-packages/sphinx/builders/__init__.py", line 251, in build_update
    'out of date' % len(to_build))
  File "/usr/local/lib/python3.4/dist-packages/sphinx/builders/__init__.py", line 265, in build
    self.doctreedir, self.app))
  File "/usr/local/lib/python3.4/dist-packages/sphinx/environment.py", line 569, in update
    self._read_serial(docnames, app)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/environment.py", line 589, in _read_serial
    self.read_doc(docname, app)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/environment.py", line 742, in read_doc
    pub.publish()
  File "/usr/local/lib/python3.4/dist-packages/docutils/core.py", line 217, in publish
    self.settings)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/io.py", line 49, in read
    self.parse()
  File "/usr/local/lib/python3.4/dist-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/__init__.py", line 172, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/usr/local/lib/python3.4/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/local/lib/python3.4/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 2726, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 395, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 282, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.4/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/local/lib/python3.4/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 2726, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 395, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 282, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.4/dist-packages/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/local/lib/python3.4/dist-packages/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 2299, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 2311, in explicit_construct
    return method(self, expmatch)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 2054, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/local/lib/python3.4/dist-packages/docutils/parsers/rst/states.py", line 2103, in run_directive
    result = directive_instance.run()
  File "/usr/local/lib/python3.4/dist-packages/sphinx/ext/autodoc.py", line 1613, in run
    documenter.generate(more_content=self.content)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/ext/autodoc.py", line 963, in generate
    self.document_members(all_members)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/ext/autodoc.py", line 854, in document_members
    classes = [cls for cls in itervalues(AutoDirective._registry)
  File "/usr/local/lib/python3.4/dist-packages/sphinx/ext/autodoc.py", line 855, in <listcomp>
    if cls.can_document_member(member, mname, isattr, self)]
  File "/usr/local/lib/python3.4/dist-packages/sphinx/ext/autodoc.py", line 1458, in can_document_member
    isdatadesc = isdescriptor(member) and not \
  File "/usr/local/lib/python3.4/dist-packages/sphinx/util/inspect.py", line 101, in isdescriptor
    if hasattr(safe_getattr(x, item, None), '__call__'):
  File "/usr/local/lib/python3.4/dist-packages/sphinx/util/inspect.py", line 113, in safe_getattr
    if name in obj.__dict__:
  File "/usr/local/lib/python3.4/dist-packages/werkzeug/local.py", line 343, in __getattr__
    return getattr(self._get_current_object(), name)
  File "/usr/local/lib/python3.4/dist-packages/werkzeug/local.py", line 302, in _get_current_object
    return self.__local()
  File "/usr/local/lib/python3.4/dist-packages/flask/globals.py", line 44, in _lookup_app_object
    raise RuntimeError(_app_ctx_err_msg)
RuntimeError: Working outside of application context.

This typically means that you attempted to use functionality that needed
to interface with the current application object in a way.  To solve
this set up an application context with app.app_context().  See the
documentation for more information.

The problem does not occur with all Flask applications. Others seem to work fine, but this one fails. However, it is a bit complex and I have not yet found out what exactly in my application causes this.

api bug

Source