Skip to content

Commit

Permalink
doc: fix readthedocs build
Browse files Browse the repository at this point in the history
Extension 'sphinxcontrib.napoleon' is not working and throwing an exception
while reading the source code files to generate the API documentation (see
below)

This commit removes the installation of that extension and adds
'sphinx.ext.napoleon' to the extensions list in 'doc/conf.py' as documented at
https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

sphinx-doc/sphinx#6237
sphinx-doc/sphinx@d34302a

Error from https://readthedocs.org/projects/xbplib/builds/11893463/

    [...]
    reading sources... [ 44%] api/digi.xbee.packets.common
    reading sources... [ 46%] api/digi.xbee.packets.devicecloud
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.XBeeDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.Raw802Device.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.DigiMeshDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.DigiPointDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.ZigBeeDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.IPDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.CellularDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.LPWANDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.NBIoTDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/devices.py:docstring of digi.xbee.devices.WiFiDevice.get_route_to_node:15: WARNING: Unexpected indentation.
    .../digi/xbee/filesystem.py:docstring of digi.xbee.filesystem.FileSystemManager.read_file:13: WARNING: Unexpected indentation.
    .../digi/xbee/filesystem.py:docstring of digi.xbee.filesystem.FileSystemManager.write_file:17: WARNING: Unexpected indentation.
    .../digi/xbee/filesystem.py:docstring of digi.xbee.filesystem.FileSystemManager.get_file:10: WARNING: Unexpected indentation.
    .../digi/xbee/filesystem.py:docstring of digi.xbee.filesystem.FileSystemManager.put_file:19: WARNING: Unexpected indentation.
    .../digi/xbee/filesystem.py:docstring of digi.xbee.filesystem.FileSystemManager.put_dir:14: WARNING: Unexpected indentation.

    Traceback (most recent call last):
      File ".../lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
        app.build(args.force_all, filenames)
      File ".../lib/python3.7/site-packages/sphinx/application.py", line 341, in build
        self.builder.build_update()
      File ".../lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
        len(to_build))
      File ".../lib/python3.7/site-packages/sphinx/builders/__init__.py", line 360, in build
        updated_docnames = set(self.read())
      File ".../lib/python3.7/site-packages/sphinx/builders/__init__.py", line 468, in read
        self._read_serial(docnames)
      File ".../lib/python3.7/site-packages/sphinx/builders/__init__.py", line 490, in _read_serial
        self.read_doc(docname)
      File ".../lib/python3.7/site-packages/sphinx/builders/__init__.py", line 534, in read_doc
        doctree = read_doc(self.app, self.env, self.env.doc2path(docname))
      File ".../lib/python3.7/site-packages/sphinx/io.py", line 318, in read_doc
        pub.publish()
      File ".../lib/python3.7/site-packages/docutils/core.py", line 217, in publish
        self.settings)
      File ".../lib/python3.7/site-packages/docutils/readers/__init__.py", line 72, in read
        self.parse()
      File ".../lib/python3.7/site-packages/docutils/readers/__init__.py", line 78, in parse
        self.parser.parse(self.input, document)
      File ".../lib/python3.7/site-packages/sphinx/parsers.py", line 88, in parse
        self.statemachine.run(inputstring, document, inliner=self.inliner)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 171, in run
        input_source=document['source'])
      File ".../lib/python3.7/site-packages/docutils/statemachine.py", line 239, in run
        context, state, transitions)
      File ".../lib/python3.7/site-packages/docutils/statemachine.py", line 460, in check_line
        return method(match, context, next_state)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2753, in underline
        self.section(title, source, style, lineno - 1, messages)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 327, in section
        self.new_subsection(title, lineno, messages)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 395, in new_subsection
        node=section_node, match_titles=True)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 282, in nested_parse
        node=node, match_titles=match_titles)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 196, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File ".../lib/python3.7/site-packages/docutils/statemachine.py", line 239, in run
        context, state, transitions)
      File ".../lib/python3.7/site-packages/docutils/statemachine.py", line 460, in check_line
        return method(match, context, next_state)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2326, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2338, in explicit_construct
        return method(self, expmatch)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2081, in directive
        directive_class, match, type_name, option_presets)
      File ".../lib/python3.7/site-packages/docutils/parsers/rst/states.py", line 2130, in run_directive
        result = directive_instance.run()
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/directive.py", line 131, in run
        documenter.generate(more_content=self.content)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 819, in generate
        self.document_members(all_members)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 740, in document_members
        check_module=members_check_module and not isattr)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 1248, in generate
        all_members=all_members)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 819, in generate
        self.document_members(all_members)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 1236, in document_members
        ModuleLevelDocumenter.document_members(self, all_members)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 740, in document_members
        check_module=members_check_module and not isattr)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 816, in generate
        self.add_content(more_content)
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 554, in add_content
        for i, line in enumerate(self.process_doc(docstrings)):
      File ".../lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py", line 514, in process_doc
        self.options, docstringlines)
      File ".../lib/python3.7/site-packages/sphinx/application.py", line 510, in emit
        return self.events.emit(event, self, *args)
      File ".../lib/python3.7/site-packages/sphinx/events.py", line 80, in emit
        results.append(callback(*args))
      File ".../lib/python3.7/site-packages/sphinxcontrib/napoleon/__init__.py", line 382, in _process_docstring
        obj, options)
      File ".../lib/python3.7/site-packages/sphinxcontrib/napoleon/docstring.py", line 180, in __init__
        self._parse()
      File ".../lib/python3.7/site-packages/sphinxcontrib/napoleon/docstring.py", line 582, in _parse
        lines = self._sections[section.lower()](section)
      File ".../lib/python3.7/site-packages/sphinxcontrib/napoleon/docstring.py", line 707, in _parse_raises_section
        m = self._name_rgx.match(_type).groupdict()  # type: ignore
    AttributeError: 'NoneType' object has no attribute 'groupdict'

    Exception occurred:
      File ".../lib/python3.7/site-packages/sphinxcontrib/napoleon/docstring.py", line 707, in _parse_raises_section
        m = self._name_rgx.match(_type).groupdict()  # type: ignore
    AttributeError: 'NoneType' object has no attribute 'groupdict'
    The full traceback has been saved in /tmp/sphinx-err-lhkjiv9z.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!

Signed-off-by: Tatiana Leon <Tatiana.Leon@digi.com>
  • Loading branch information
tatianaleon committed Oct 30, 2020
1 parent 22a081d commit 14f14dd
Show file tree
Hide file tree
Showing 2 changed files with 1 addition and 2 deletions.
2 changes: 1 addition & 1 deletion doc/conf.py
Expand Up @@ -34,7 +34,7 @@
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinxcontrib.napoleon',
"sphinx.ext.napoleon",
]

# Add any paths that contain templates here, relative to this directory.
Expand Down
1 change: 0 additions & 1 deletion requirements.txt
@@ -1,3 +1,2 @@
pyserial>=3
sphinxcontrib-napoleon
srp

0 comments on commit 14f14dd

Please sign in to comment.