9

アプリケーションでサポートされているすべての URL のコードからドキュメントを自動的に作成しようとしています。完全にクライアント側の MVC を使用しているため、サポートされている各 URL は基本的に UI 用の REST API です。これらの URL からドキュメントを生成する簡単な方法はありますか?

私は今のところこの小さなモジュールを書いていますが、これよりも良い方法を探しています。似たようなものがすでに存在する場合、車輪を再発明したくありません。

更新: 内部消費用ではなく、Web サイトの消費者に公開ドキュメントを提供することを目的としていることに注意してください。この点に関して、各 URL について次のことを文書化する必要があります。

単純にホームページにリダイレクトする (^$) のような特定の 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) を文書化する必要があります。また、1 つの文書で呼び出すことができるディレクティブを公開する独自の拡張機能を作成して、まさにあなたがしたことを行うことができます。ここでやっています。

または、これを完全に回避することもできます: Sphinx ドキュメントを手動で管理し、Github リポジトリを作成し、https: //readthedocs.org/ でドキュメントをホストします!

于 2012-11-19T18:51:48.293 に答える
1

誰かが興味を持っている場合に備えて、最終更新です。

最終的に、私が持っているコード スニペットを内部目的で使用することになりました。プロジェクトの最後にデベロッパー ガイドを作成するとき、パブリック ベータの準備ができたときに、Sphinx に挑戦してそれを使用することにしました。これは、学習やロジスティクスなどに時間と投資が必要になるためです。

于 2013-01-11T22:11:23.740 に答える