From da31db0eaa96760d5735a27a9ec53d18608a56d4 Mon Sep 17 00:00:00 2001 From: Tatiana Leon Date: Thu, 29 Oct 2020 16:35:33 +0100 Subject: [PATCH] doc: fix readthedocs build 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 https://github.com/sphinx-doc/sphinx/pull/6237 https://github.com/sphinx-doc/sphinx/commit/d34302a41514f82075dea8d1e6b1088f6e57768a 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 . Thanks! Signed-off-by: Tatiana Leon --- doc/conf.py | 2 +- requirements.txt | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 2998545..026ea4e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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. diff --git a/requirements.txt b/requirements.txt index 2f9b639..9e8c9f9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,2 @@ pyserial>=3 -sphinxcontrib-napoleon srp \ No newline at end of file