0

我有一个 Django 网站，并创建了一个 REST api。在视图函数中，我有关于 REST url 的文档，并且我想为 REST url 生成 API 文档。视图函数如下所示：

def genres(request):
    """
    Url: /api/genres/
    Parameters: None
    Returns: list of genres { { "id":1, "name":"action" }, {...} }
    """
    pass

但是当我在 myproject.api.views 上运行 sphinx 时，我得到了用于在 python 中调用 api 的 html 文档。有没有办法配置 sphinx 像 REST api 一样记录它？

还是我最好自己编写一个脚本来从文档字符串中生成我的文档？

4

1 回答 1

0

检查sphinxcontrib-httpdomain

您可以使用 autodoc 来使用 docstrings 和 httpdomain 扩展名来使用 .. http:get:: /users/ 样式指令。这个解决方案有一个问题，它还会显示函数的签名。为了解决这个问题，我对 Sphinx 源代码进行了一些修改，制作了一个不会将签名添加到最终文档中的原始 autodoc 扩展的副本。

这些文件可以在https://gist.github.com/4589457上找到

指示：

  1. 将sphinx 路径上的application.py替换为gist上的路径（我系统上的路径是 /Library/Frameworks/Python.framework/Versions/Current/lib/python2.7/site-packages/Sphinx-1.1.3-py2 .7.egg/狮身人面像/)
  2. 在 ext 文件夹中添加simpleautodoc.py
  3. 在 conf.py 上添加httpdomain扩展，以便使用 .. http:get:: /users/ 样式指令
  4. 使用 simpleautodoc，就像使用前缀autosimple而不是 auto 一样使用 autodoc（例如 autosimplemodule 而不是 automodule autosimpleclass 而不是 autoclass 等）
  5. example.py文件显示了我如何格式化文档字符串的示例
于 2013-01-21T14:50:02.837 回答