Question

我有一个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？

或者我最好自己写一个脚本来从文档字符串生成我的文档？

Answer 1

检查sphinxcontrib-httpdomain

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

可以在https://gist.github.com/4589457

上找到这些文件

说明：

将sphinx路径上的 application.py 替换为gist上的那个（我系统上的路径是/Library/Frameworks/Python.framework/Versions/Current/lib/python2 0.7 /站点包/斯芬克斯-1.1.3-py2.7.egg /斯芬克斯/）
在ext文件夹

simpleautodoc.py

在conf.py上添加 httpdomain 扩展名以便使用.. http：get :: / users / style directives
使用simpleautodoc就像使用autodoc一样，使用前缀 autosimple 而不是auto（例如autosimplemodule而不是automodule autosimpleclass而不是autoclass等）
example.py 文件显示了如何格式化文档字符串的示例

如何从python docstrings生成Web API文档

1 个答案: