search

readthedocs / sphinx-autoapi

A new approach to API documentation in Sphinx.
https://sphinx-autoapi.readthedocs.io/
MIT License
439 stars 131 forks source link

Go bug with Sphinx v2: Could not import extension sphinxcontrib_golangdomain #207

Closed jwflory closed 4 years ago

jwflory commented 4 years ago

Continued from #196.

Summary

sphinxcontrib_golangdomain is not found as an extension when added to conf.py even when installed

Background

I followed the instructions in the Go tutorial, but when I go to build my docs with sphinx-build, this is the output:

Running Sphinx v2.4.4

Extension error:
Could not import extension sphinxcontrib_golangdomain \
    (exception: No module named 'sphinxcontrib_golangdomain')

I tested this with Sphinx 2.4.4 and 3.0.1 and got the same result.

Details

Somehow Sphinx is not finding the extension, even though it is in my conf.py file:

extensions = [
    'autoapi.extension',
    'recommonmark',
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.imgmath',
    'sphinx.ext.viewcode',
    'sphinxcontrib_golangdomain',
]

Not sure if there is more helpful debug output I can provide, but let me know what to do if more verbosity is needed somewhere.

Outcome

Blocks using Sphinx-AutoAPI for Go code

xXPhenomXx commented 4 years ago

Same issue here, golang 1.14.2

PS I:\Development-Linux\Go\src\tshoot\docs> sphinx-build -b html . _build Running Sphinx v3.0.3

Extension error: Could not import extension sphinxcontrib_golangdomain (exception: No module named >'sphinxcontrib_golangdomain')

AWhetter commented 4 years ago

There was a typo in the documentation. The module name should be sphinxcontrib.golangdomain. Thanks for the report!

xXPhenomXx commented 4 years ago

This is the error I am getting now with the typo correction:

PS I:\Development-Linux\Go\src\tshoot\docs> sphinx-build -b html . _build
Running Sphinx v3.0.3

Extension error:
Could not import extension sphinxcontrib.golangdomain (exception: cannot import name 'l_' from 'sphinx.locale' (c:\users\jasse\appdata\local\programs\python\python38\lib\site-packages\sphinx\locale\__init__.py))

My init.py

extensions = [
    # 'autoapi.extension',
    #  'sphinx.ext.autodoc',
    # 'sphinx.ext.todo',
    # 'sphinx.ext.imgmath',
    # 'sphinx.ext.viewcode',
    'sphinxcontrib.golangdomain',
]

autoapi_type = 'go'

autoapi_dirs = ['../']
jwflory commented 4 years ago

@xXPhenomXx I was able to replicate the same error with Sphinx v3.0.3 too. You need to downgrade to Sphinx v2.4.4.

However, with Sphinx v2.4.4, I get a fatal exception now:

$ make clean html ```sh Removing everything under '_build'... Running Sphinx v2.4.4 /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:54: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. TypedField('parameter', label=l_('Parameters'), /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:57: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. Field('returnvalue', label=l_('Returns'), has_arg=False, /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:59: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. Field('returntype', label=l_('Return type'), has_arg=False, /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:318: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. localname = l_('Golang Package Index') /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:319: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. shortname = l_('packages') /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:386: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. 'function': ObjType(l_('function'), 'func'), /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:387: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. 'package': ObjType(l_('package'), 'pkg'), /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:388: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. 'type': ObjType(l_('function'), 'type'), /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:389: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. 'var': ObjType(l_('variable'), 'data'), /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py:390: RemovedInSphinx30Warning: sphinx.locale.l_() is deprecated. Please use `_()` instead. 'const': ObjType(l_('const'), 'data'), making output directory... done [AutoAPI] Loading Data [100%] /home/jflory/git/rit/ritlug/teleirc/internal [AutoAPI] Mapping Data... [100%] /home/jflory/git/rit/ritlug/teleirc/internal [AutoAPI] Rendering Data... [ 50%] main [AutoAPI] Rendering Data... [100%] internal building [mo]: targets for 0 po files that are out of date building [html]: targets for 10 source files that are out of date updating environment: [new config] 13 added, 0 changed, 0 removed /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document warn("Container node skipped: type={0}".format(mdnode.t)) /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/autoapi/extension.py:210: FutureWarning: The iterable returned by Node.traverse() will become an iterator instead of a list in Docutils > 0.16. nodes[-1]["entries"].append((None, u"%s/index" % app.config.autoapi_root)) [AutoAPI] Adding AutoAPI TOCTree [autoapi/index] to index.rst reading sources... [100%] quick-install /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:19: WARNING: Unknown directive type "go:method". .. go:method:: Error /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:34: WARNING: Unknown directive type "go:method". .. go:method:: LogDebug LogDebug prints debug-level messages to standard out :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:43: WARNING: Unknown directive type "go:method". .. go:method:: LogError LogError prints error-level messages to standard out :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:52: WARNING: Unknown directive type "go:method". .. go:method:: LogInfo LogInfo prints info-level messages to standard out :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:61: WARNING: Unknown directive type "go:method". .. go:method:: LogWarning LogWarning prints warning-level messages to standard out :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:70: WARNING: Unknown directive type "go:method". .. go:method:: PrintVersion PrintVersion prints the TeleIRC version number :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:115: WARNING: Unknown directive type "go:method". .. go:method:: EXPECT EXPECT returns an object that allows the caller to indicate expected use /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:122: WARNING: Unknown directive type "go:method". .. go:method:: LogDebug LogDebug mocks base method :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:131: WARNING: Unknown directive type "go:method". .. go:method:: LogError LogError mocks base method :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:140: WARNING: Unknown directive type "go:method". .. go:method:: LogInfo LogInfo mocks base method :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:149: WARNING: Unknown directive type "go:method". .. go:method:: LogWarning LogWarning mocks base method :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:167: WARNING: Unknown directive type "go:method". .. go:method:: PrintVersion PrintVersion mocks base method :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:185: WARNING: Unknown directive type "go:method". .. go:method:: LogDebug LogDebug indicates an expected call of LogDebug :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:194: WARNING: Unknown directive type "go:method". .. go:method:: LogError LogError indicates an expected call of LogError :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:203: WARNING: Unknown directive type "go:method". .. go:method:: LogInfo LogInfo indicates an expected call of LogInfo :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:212: WARNING: Unknown directive type "go:method". .. go:method:: LogWarning LogWarning indicates an expected call of LogWarning :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:221: WARNING: Unknown directive type "go:method". .. go:method:: PrintVersion PrintVersion indicates an expected call of PrintVersion :param v: :type v: ...interface{} /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:2: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal (package)', 'package-internal', 'internal')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.ConfigErrors (Golang type)', 'internal.ConfigErrors', 'internal.ConfigErrors')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.Debug (Golang type)', 'internal.Debug', 'internal.Debug')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.DebugLogger (Golang type)', 'internal.DebugLogger', 'internal.DebugLogger')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.IRCSettings (Golang type)', 'internal.IRCSettings', 'internal.IRCSettings')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.ImgurSettings (Golang type)', 'internal.ImgurSettings', 'internal.ImgurSettings')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.MockDebugLogger (Golang type)', 'internal.MockDebugLogger', 'internal.MockDebugLogger')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.MockDebugLoggerMockRecorder (Golang type)', 'internal.MockDebugLoggerMockRecorder', 'internal.MockDebugLoggerMockRecorder')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.Settings (Golang type)', 'internal.Settings', 'internal.Settings')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/internal/index.rst:4: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'internal.TelegramSettings (Golang type)', 'internal.TelegramSettings', 'internal.TelegramSettings')] /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/main/index.rst:2: WARNING: 4 column based index found. It might be a bug of extensions you use: [('single', 'main (package)', 'package-main', 'main')] looking for now-outdated files... none found pickling environment... done checking consistency... /home/jflory/git/rit/ritlug/teleirc/docs/autoapi/index.rst: WARNING: document isn't included in any toctree done preparing documents... failed Exception occurred: File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py", line 327, in generate packages = sorted(self.domain.data['packages'].iteritems(), AttributeError: 'dict' object has no attribute 'iteritems' ```
$ cat /tmp/sphinx-err-vtb0y2j9.log ```python # Sphinx version: 2.4.4 # Python version: 3.8.2 (CPython) # Docutils version: 0.16 release # Jinja2 version: 3.0.0a1 # Last messages: # reading sources... [100%] quick-install # # looking for now-outdated files... # none found # pickling environment... # done # checking consistency... # done # preparing documents... # failed # Loaded extensions: # sphinx.ext.mathjax (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/mathjax.py # sphinxcontrib.applehelp (1.0.2) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/applehelp/__init__.py # sphinxcontrib.devhelp (1.0.2) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/devhelp/__init__.py # sphinxcontrib.htmlhelp (1.0.3) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/htmlhelp/__init__.py # sphinxcontrib.serializinghtml (1.1.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py # sphinxcontrib.qthelp (1.0.3) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/qthelp/__init__.py # alabaster (0.7.12) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/alabaster/__init__.py # sphinx.ext.autodoc.type_comment (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/autodoc/type_comment.py # sphinx.ext.autodoc (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/autodoc/__init__.py # sphinx.ext.autosummary (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/autosummary/__init__.py # sphinx.ext.graphviz (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/graphviz.py # sphinx.ext.inheritance_diagram (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/inheritance_diagram.py # autoapi.extension (unknown version) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/autoapi/extension.py # recommonmark (0.6.0) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/recommonmark/__init__.py # sphinx.ext.todo (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/todo.py # sphinx.ext.imgmath (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/imgmath.py # sphinx.ext.viewcode (2.4.4) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/ext/viewcode.py # sphinxcontrib.golangdomain (unknown version) from /home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py Traceback (most recent call last): File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main app.build(args.force_all, filenames) File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/application.py", line 349, in build self.builder.build_update() File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 297, in build_update self.build(to_build, File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 361, in build self.write(docnames, list(updated_docnames), method) File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 527, in write self.prepare_writing(docnames) File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinx/builders/html.py", line 450, in prepare_writing content, collapse = indexcls(domain).generate() File "/home/jflory/.local/share/virtualenvs/docs-w60xKFra/lib/python3.8/site-packages/sphinxcontrib/golangdomain.py", line 327, in generate packages = sorted(self.domain.data['packages'].iteritems(), AttributeError: 'dict' object has no attribute 'iteritems' ```
jwflory commented 4 years ago

@AWhetter Should I open a new issue for this or do you want to track this bug in this issue?