0
我正在尝试生成flask-restful的扩展文件，以便生成RESTful API。我的最终目标是使用doc2dash生成短划线文档。使用sphinx生成砂箱扩展的文档
但是，在我可以这样做之前，我需要使用sphinx生成所需的html。在我尝试这样做的过程中，我克隆了flask-restful project，并尝试使用make html从其docs文件夹生成文档。但是，我收到了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.ext.restful。但是，由于此文档的生成需要源代码，因此该模块被称为flask_restful，因此sphinx无法找到它并因此引发并且ImportError。下面是这棵树的样子：
.
├── 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？
更新，以下安蒂的意见后，这是它涉及到：
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.