我正在尝试flask-restful为烧瓶的扩展生成文档，以便轻松生成 RESTful API。我的最终目标是用于doc2dash生成破折号文档测试。
但是，在执行此操作之前，我需要使用sphinx. 在我尝试这样做时，我克隆了flask-restful 项目，并尝试从其docs文件夹中生成文档，使用make html. 但是，我收到 17 个警告，并且生成的文档不完整。这是回溯：
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.2.3
loading pickled environment... not yet created
loading intersphinx inventory from http://flask.pocoo.org/docs/objects.inv...
building [html]: targets for 9 source files that are out of date
updating environment: 9 added, 0 changed, 0 removed
reading sources... [100%] testing
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:9: WARNING: autodoc: failed to import function u'marshal' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:10: WARNING: autodoc: failed to import function u'marshal_with' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:11: WARNING: autodoc: failed to import function u'marshal_with_field' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:12: WARNING: autodoc: failed to import function u'abort' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:17: WARNING: autodoc: failed to import class u'Api' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:22: WARNING: autodoc: failed to import class u'Resource' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:27: WARNING: autodoc: failed to import module u'reqparse'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/flask_restful/reqparse.py", line 3, in <module>
import flask_restful
ImportError: No module named flask_restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:30: WARNING: autodoc: failed to import class u'Argument' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:37: WARNING: autodoc: failed to import module u'fields'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/flask_restful/fields.py", line 9, in <module>
from flask_restful import inputs, marshal
ImportError: No module named flask_restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:41: WARNING: Title underline too short.
Inputs
-----
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:41: WARNING: Title underline too short.
Inputs
-----
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:44: WARNING: autodoc: failed to import function u'url' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:45: WARNING: autodoc: failed to import function u'date' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:46: WARNING: autodoc: failed to import function u'iso8601interval' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:47: WARNING: autodoc: failed to import function u'natural' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:48: WARNING: autodoc: failed to import function u'boolean' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:49: WARNING: autodoc: failed to import function u'rfc822' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/.pyenv/versions/2.7.6/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] testing
writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 17 warnings.
Build finished. The HTML pages are in _build/html.
通过查看结果，可以看出问题在于文档中的 flask-restful 扩展被称为 ask flask.ext.restful。但是，由于此文档的生成需要源代码，sphinx因此无法找到它并因此引发 and ImportError，因为该模块被调用flask_restful。这是树的样子：
.
├── docs
│ ├── _build
│ ├── _static
│ ├── _templates
│ └── _themes
│ ├── flask
│ │ └── static
│ └── flask_small
│ └── static
├── examples
├── flask_restful <---------- Not flask.ext.restful
│ ├── representations
│ └── utils
├── scripts
└── tests
所以，问题是我如何sphinx理解这flask.ext.restful实际上是flask_restful？
更新，在遵循 Antti 的建议之后，这就是它的结果：
rm -rf _build/*
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.2.3
loading pickled environment... not yet created
loading intersphinx inventory from http://flask.pocoo.org/docs/objects.inv...
building [html]: targets for 9 source files that are out of date
updating environment: 9 added, 0 changed, 0 removed
reading sources... [100%] testing
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:11: WARNING: autodoc: failed to import function u'marshal_with_field' from module u'flask.ext.restful'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 342, in import_object
obj = self.get_attr(obj, part)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 241, in get_attr
return safe_getattr(obj, name, *defargs)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/util/inspect.py", line 114, in safe_getattr
raise AttributeError(name)
AttributeError: marshal_with_field
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:37: WARNING: autodoc: failed to import module u'fields'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/flask_restful/fields.py", line 9, in <module>
from flask_restful import inputs, marshal
ImportError: cannot import name inputs
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:41: WARNING: Title underline too short.
Inputs
-----
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:41: WARNING: Title underline too short.
Inputs
-----
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:44: WARNING: autodoc: failed to import function u'url' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful.inputs
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:45: WARNING: autodoc: failed to import function u'date' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful.inputs
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:46: WARNING: autodoc: failed to import function u'iso8601interval' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful.inputs
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:47: WARNING: autodoc: failed to import function u'natural' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful.inputs
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:48: WARNING: autodoc: failed to import function u'boolean' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful.inputs
/Users/quazinafiulislam/Code/Python/restful/docs/api.rst:49: WARNING: autodoc: failed to import function u'rfc822' from module u'flask.ext.restful.inputs'; the following exception was raised:
Traceback (most recent call last):
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 335, in import_object
__import__(self.modname)
File "/Users/quazinafiulislam/Code/Python/restful/.venv/lib/python2.7/site-packages/flask/exthook.py", line 87, in load_module
raise ImportError('No module named %s' % fullname)
ImportError: No module named flask.ext.restful.inputs
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] testing
writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 10 warnings.
Build finished. The HTML pages are in _build/html.