9

我正在尝试从我的应用程序支持的所有 URL 的代码中自动创建文档。我们完全使用客户端 MVC，因此支持的每个 URL 本质上都是 UI 的 REST API。有没有一种简单的方法可以从这些 URL 生成文档？

到目前为止，我编写了这个小模块，但我正在寻找更好的方法。如果已经存在类似的东西，我不想重新发明轮子。

更新：请注意，其目的是为网站的消费者提供公共文档，而不是供内部使用。在这方面，对于每个 URL，我们需要记录： - 响应是什么， - 接受哪些参数， - URL 是否响应 GET/POST 或两者，等等。

某些 URL（如 (^$) 仅重定向到主页不应记录在案，因此我还需要一些排除机制。

from django.core.management.base import BaseCommand
from django.conf import settings


class Command(BaseCommand):
''' Generates documentation for the URLs.  For each URL includes the documentation from
the callback implementing the URL and prints the default arguments along with the URL pattern and name'''

    def handle(self, *args, **options):
        url_module = None
        exec 'import '+settings.ROOT_URLCONF+'; url_module='+settings.ROOT_URLCONF
        doc = file('doc.html','w')
        doc.write("<table border=1 cellspacing=0 cellpadding=5>")
        doc.write("<tr><th>URL Pattern<th>Name<th>Documentation<th>Parameters")
        for x in url_module.urlpatterns:
            doc.write("<tr>")
            doc.write("<td>")
            doc.write(x._regex)
            doc.write("<td>")
            doc.write(str(x.name))
            try:
                documentation = str(x.callback.__doc__)
                doc.write("<td><pre>")
                doc.write(documentation)
                doc.write("</pre>")
            except:
                doc.write("<td> Unable to find module")
            doc.write("<td>")
            doc.write(str(x.default_args))
        doc.write("</table>")
        doc.close()
4

2 回答 2

4

您可以从根模块遍历 URL 模式并内省视图函数对象以像您一样获取文档数据，但我宁愿通过模板呈现它以编译文档。

不过，我建议您使用Sphinx。您可能需要记录的不仅仅是您的端点（使用条款、隐私政策、身份验证、yadda yadda），并且您可以编写自己的扩展程序，该扩展程序将公开一个指令，您可以在一个文档中调用该指令来完成您所做的事情一直在这里。

或者你可以完全避免设计这个：手动管理你的 Sphinx 文档，创建一个 Github 存储库并在https://readthedocs.org/上托管文档！

于 2012-11-19T18:51:48.293 回答
1

只是一个最终更新，以防万一有人感兴趣。

我们最终将我拥有的代码片段用于内部目的。我们决定冒险进入 Sphinx 并使用它，当我们在项目结束时创建开发者指南时，当我们准备好公开测试版时，因为它需要一些时间和投资来学习、后勤等。

于 2013-01-11T22:11:23.740 回答