Question

我正在尝试为flask-restful生成文档扩展，以便于生成RESTful API。我的最终目标是使用doc2dash生成破折号文档测试。

但是，在我这样做之前，我需要使用sphinx生成所需的html。在我尝试这样做时，我克隆了flask-restful project，并尝试使用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.

通过查看结果，我们可以看到问题在于，在文档中，烧瓶 - restful扩展名被称为flask.ext.restful。但是，由于生成此文档需要源代码，sphinx无法找到它，因此会引发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.

Answer 1

如果你想从SCM安装一个模块（git，hg等checkout），并且没有太大的痛苦，那么：

创建virtualenv
将工作副本签出到您想要的任何地方（不一定在项目文件夹中），
将virtualenv中开发模式中签出的模块与
链接起来
```
python setup.py develop
```
如果支持，或
```
python setup.py install
```
如果需要安装。

执行这些步骤后，flask_restful应该可以导入为flask.ext.restful。

使用sphinx生成烧瓶扩展的文档

1 个答案: