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.