doc: remove workaround for sphinx issue once 1.5 is releaed

[nashif]

Reported by Inaky Perez-Gonzalez:

Sphinx fixed https://github.com/michaeljones/breathe/issues/267, which will be released into 1.5.

When said release is available, we can remove workaround https://www.zephyrproject.org/doc/contribute/doxygen/typedefs.html#function-definitions also documented in https://www.zephyrproject.org/doc/contribute/doxygen/troubleshooting.html.

(Imported from Jira ZEP-491)

[nashif]

by Javier B Perez:

We will work on it, as soon as the release is available.

[nashif]

by David Kinder:

Javier B Perez Looks like we're still using sphinx 1.4.4 and there's a 1.4.9 available, but 1.5 isn't released yet. Guess we're waiting for 1.5, right Inaky Perez-Gonzalez ?

[nashif]

by Javier B Perez:

I'm going to leave this unassigned till there is a sphinx 1.5 release.

[nashif]

by Sharron LIU:

Priority recovered, while keep unassigned for pending on external release.

[nashif]

by Sharron LIU:

Javier B Perez , keep it in your plate till the external release available. Thanks.

[nashif]

by Javier B Perez:

The release is now available, but breathe is not working yet with 1.5.

# Sphinx version: 1.5
# Python version: 2.7.11 (CPython)
# Docutils version: 0.12 release
# Jinja2 version: 2.8
# Last messages:
#   loading pickled environment...
#   not yet created
#   building [mo]: targets for 0 po files that are out of date
#   building [html]: targets for 1921 source files that are out of date
#   updating environment:
#   1921 added, 0 changed, 0 removed
#   reading sources... [  0%] LICENSING
#   reading sources... [  0%] README
#   reading sources... [  0%] api/api
#   reading sources... [  0%] api/bluetooth
# Loaded extensions:
#   sphinx.domains.cpp (unknown version) from /usr/lib/python2.7/site-packages/sphinx/domains/cpp.pyc
#   sphinx.builders.applehelp (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/applehelp.pyc
#   sphinx.directives (unknown version) from /usr/lib/python2.7/site-packages/sphinx/directives/__init__.pyc
#   sphinx.builders.changes (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/changes.pyc
#   sphinx.builders.websupport (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/websupport.pyc
#   sphinx.domains.c (unknown version) from /usr/lib/python2.7/site-packages/sphinx/domains/c.pyc
#   sphinx.builders.dummy (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/dummy.pyc
#   sphinx.builders.texinfo (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/texinfo.pyc
#   sphinx.builders.epub (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/epub.pyc
#   sphinx.builders.linkcheck (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/linkcheck.pyc
#   sphinx.domains.std (unknown version) from /usr/lib/python2.7/site-packages/sphinx/domains/std.pyc
#   sphinx.directives.other (unknown version) from /usr/lib/python2.7/site-packages/sphinx/directives/other.pyc
#   sphinx.builders.epub3 (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/epub3.pyc
#   sphinx.ext.todo (1.5) from /usr/lib/python2.7/site-packages/sphinx/ext/todo.pyc
#   sphinx.domains.javascript (unknown version) from /usr/lib/python2.7/site-packages/sphinx/domains/javascript.pyc
#   sphinx.directives.code (unknown version) from /usr/lib/python2.7/site-packages/sphinx/directives/code.pyc
#   breathe (4.4.0) from /usr/lib/python2.7/site-packages/breathe/__init__.pyc
#   sphinx.ext.autodoc (1.5) from /usr/lib/python2.7/site-packages/sphinx/ext/autodoc.pyc
#   alabaster (0.7.9) from /usr/lib/python2.7/site-packages/alabaster/__init__.pyc
#   sphinx.builders.text (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/text.pyc
#   sphinx.builders.qthelp (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/qthelp.pyc
#   sphinx.roles (unknown version) from /usr/lib/python2.7/site-packages/sphinx/roles.pyc
#   sphinx.builders.htmlhelp (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/htmlhelp.pyc
#   sphinx.directives.patches (unknown version) from /usr/lib/python2.7/site-packages/sphinx/directives/patches.pyc
#   sphinx.builders.latex (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/latex.pyc
#   sphinx.builders.html (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/html.pyc
#   sphinx.builders.devhelp (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/devhelp.pyc
#   sphinx.builders.gettext (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/gettext.pyc
#   sphinx.builders.xml (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/xml.pyc
#   sphinx.builders.manpage (unknown version) from /usr/lib/python2.7/site-packages/sphinx/builders/manpage.pyc
#   sphinx.domains.rst (unknown version) from /usr/lib/python2.7/site-packages/sphinx/domains/rst.pyc
#   sphinx.domains.python (unknown version) from /usr/lib/python2.7/site-packages/sphinx/domains/python.pyc
Traceback (most recent call last):
  File "/usr/lib/python2.7/site-packages/sphinx/cmdline.py", line 296, in main
    app.build(opts.force_all, filenames)
  File "/usr/lib/python2.7/site-packages/sphinx/application.py", line 333, in build
    self.builder.build_update()
  File "/usr/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 251, in build_update
    'out of date' % len(to_build))
  File "/usr/lib/python2.7/site-packages/sphinx/builders/__init__.py", line 265, in build
    self.doctreedir, self.app))
  File "/usr/lib/python2.7/site-packages/sphinx/environment/__init__.py", line 549, in update
    self._read_serial(docnames, app)
  File "/usr/lib/python2.7/site-packages/sphinx/environment/__init__.py", line 569, in _read_serial
    self.read_doc(docname, app)
  File "/usr/lib/python2.7/site-packages/sphinx/environment/__init__.py", line 677, in read_doc
    pub.publish()
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/core.py", line 217, in publish
    self.settings)
  File "/usr/lib/python2.7/site-packages/sphinx/io.py", line 55, in read
    self.parse()
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/__init__.py", line 172, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 170, in run
    input_source=document['source'])
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 2726, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 395, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 282, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 2726, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 395, in new_subsection
    node=section_node, match_titles=True)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 282, in nested_parse
    node=node, match_titles=match_titles)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 2299, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 2311, in explicit_construct
    return method(self, expmatch)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 2054, in directive
    directive_class, match, type_name, option_presets)
  File "/usr/lib/python2.7/site-packages/docutils-0.12-py2.7.egg/docutils/parsers/rst/states.py", line 2103, in run_directive
    result = directive_instance.run()
  File "/usr/lib/python2.7/site-packages/breathe/directives.py", line 410, in run
    node_list.extend(object_renderer.render(context.node_stack[0], context))
  File "/usr/lib/python2.7/site-packages/breathe/renderer/sphinxrenderer.py", line 1156, in render
    result = method(self, node)
  File "/usr/lib/python2.7/site-packages/breathe/renderer/sphinxrenderer.py", line 1096, in dispatch_memberdef
    return self.visit_enum(node)
  File "/usr/lib/python2.7/site-packages/breathe/renderer/sphinxrenderer.py", line 938, in visit_enum
    update_signature=update_signature)
  File "/usr/lib/python2.7/site-packages/breathe/renderer/sphinxrenderer.py", line 313, in render_declaration
    update_signature(signode, obj_type)
  File "/usr/lib/python2.7/site-packages/breathe/renderer/sphinxrenderer.py", line 935, in update_signature
    signature.children[1][0] = self.node_factory.strong(text="[anonymous]")
IndexError: list index out of range

[nashif]

by Javier B Perez:

Update

sudo -E pip install -U Sphinx
sudo -E pip install -U pyopenssl
sudo -E pip install -U breathe

Version

Successfully installed Sphinx-1.5 alabaster-0.7.9 pytz-2016.10 requests-2.12.3
Successfully installed cffi-1.9.1 cryptography-1.6 enum34-1.1.6 idna-2.1 ipaddress-1.0.17 pyasn1-0.1.9 pycparser-2.17 pyopenssl-16.2.0 setuptools-30.2.0
Successfully installed breathe-4.4.0

[nashif]

by Carles Cufi:

Update: Downgrading to Sphinx 1.4.9 from 1.5.1 fixes this issue, but a new one appears:

Exception occurred:
  File "/usr/local/lib/python2.7/dist-packages/docutils/writers/_html_base.py", line 671, in depart_document
    assert not self.context, 'len(context) = %s' % len(self.context)
AssertionError: len(context) = 2
The full traceback has been saved in /tmp/sphinx-err-iXTEBY.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!
Makefile:76: recipe for target 'html' failed
make[1]: *** [html] Error 1
Makefile:1199: recipe for target 'htmldocs' failed
make: *** [htmldocs] Error 2

I'm getting the same error:

File "/usr/lib/python2.7/site-packages/breathe/renderer/sphinxrenderer.py", line 935, in update_signature
    signature.children[1][0] = self.node_factory.strong(text="[anonymous]")
IndexError: list index out of range

With the following versions:

adium-theme-ubuntu (0.3.4)
alabaster (0.7.9)
Babel (2.3.4)
backports.ssl-match-hostname (3.5.0.1)
breathe (4.4.0)
docutils (0.13.1)
enum34 (1.1.6)
future (0.16.0)
imagesize (0.7.1)
intelhex (2.1)
Jinja2 (2.9.4)
MarkupSafe (0.23)
pip (9.0.1)
pycrypto (2.6.1)
Pygments (2.1.3)
pyOCD (0.8.1a2.dev1)
pytz (2016.10)
pyusb (1.0.0)
requests (2.12.5)
setuptools (26.1.1)
six (1.10.0)
snowballstemmer (1.2.1)
Sphinx (1.5.1)
ubuntuone-client-data (14.4)
unity-lens-photos (1.0)
websocket-client (0.40.0)
wheel (0.29.0)

[nashif]

by David Kinder:

The " assert not self.context, 'len(context) = %s' % len(self.context)" error comes from an incompatibility between sphinx 1.4.* and docutils 0.13

Check which version of docutils you have (using "pip show docutils") and if it's 0.13 you can change it to 0.12 by using "pip install docutils==0.12" (or "sudo -H pip install docutils==0.12")

(I've documented this in doc/README.rst )

[nashif]

by Carles Cufi:

David Kinder : Thanks for that. That said, Anas Nashif mentioned that he's running sphinx 1.5.1 and breathe 4.4.0 and has no issues generating the doc, so I am now unsure whether I should downgrade my Sphinx installation or find out what's going on with this combination.

[nashif]

by David Kinder:

Ah OK. I'll poke around sphinx 1.5.1 today and see what's up with versions

[nashif]

by Carles Cufi:

David Kinder : OK I think I should've read the docs first instead of searching Jira. By using the versions recommended in doc/README.rst it now all works correcty. Thanks for pointing me to that README file, I simply didn't know it existed.

[nashif]

by David Kinder:

Anas Nashif I read above you've got Sphinx 1.5.1 and breathe 4.4.0 working. Can you let me know what version of doxygen and docutils you're using. (I'm failing with that combo with doxygen 1.8.11)

[nashif]

by Anas Nashif:

some combination worked,

sphinx 1.5 is released, why do we still have this bug?

[nashif]

by Mark Linkmeyer:

Fixed priority error

[nashif]

Related to GH-1503