Sphinx は、一連の ReST 形式のテキスト ファイルから適切なドキュメントを生成する Python ライブラリです。全文検索に使用されるツールではない
また、doxygen / phpdoc ツールについても十分に認識しています。Sphinx を使用して PHP プロジェクトを文書化する方法があるかどうかを調べようとしていますか? または、他の非 Python 言語でさえありますか?
質問する
11013 次
5 に答える
26
私の経験では、Sphinx と ReST は一般的なドキュメント ツールとして使用できます。Sphinx については、Python ベースのプロジェクトにのみ使用する義務はありません。たとえば、私の仕事では、これを使用してユーザー ガイドと XML-RPC API リファレンスを作成しました。どちらの場合も、sphinx.ext.autodocまたはその他の Python 固有のエクストラは使用しませんでした。ドキュメンテーションは、Sphinx が提供する特殊なディレクティブではなく、ほとんどが一般的な ReST ディレクティブを使用して「手作業で」作成されました。価値のあることとして、Python 以外のドキュメント用のカスタム ReST ディレクティブを作成する必要はまだありません。
PHP プロジェクトで作業している場合でも、Sphinx が役立つことがわかると思います。たとえば、モジュール固有のマークアップによって提供されるディレクティブのほとんどは、実際には非常に一般的です。Python 以外の言語からのものを文書化するために、これらの構成要素を使用できない、または使用しない理由がわかりません。同様に、Sphinx を使用すると、他の言語のコード例を簡単に表示できます。Pygments がサポートする任意の言語 (PHP を含む) にデフォルトを変更する構成値もあります。特に野心がある場合は、Sphinx 拡張機能を作成して、PHP コードから関連するものを抜き出すこともできます。
とはいえ、ドキュメンテーション プロジェクトの対象者を必ず考慮してください。Sphinx は優れたツールであり、幅広いドキュメンテーション プロジェクトに推奨できると思いますが、視聴者が何か他のものを期待している場合は、その点に注意してください。たとえば、Java プロジェクトのドキュメントを作成している場合、読者の多くは Javadoc スタイルのドキュメントを期待している可能性があります。その期待から逸脱した場合は、それがただのキックではなく (つまり、他の方法よりも優れたドキュメントが得られる) ことを確認し、(簡単に) 自分が別の方法で行ったことを主張する準備をしてください (たとえば、よくある質問の回答または紹介）。
最後に、ドキュメントの作成に使用したツールに関係なく、ドキュメントはドキュメントがないよりはましです。それが何かをそこに出すかどうかの違いである場合は、あなたを助けるツールを使用してください。
于 2009-11-19T00:45:59.887 に答える
7
数日前にリリースされたばかり: http://mark-story.com/posts/view/sphinx-phpdomain-released
于 2011-04-26T05:56:26.867 に答える
4
CakePHP は新しいドキュメントに Sphinx を使用しており、私は sphinx の phpdomain を書きました。php doc ブロックを自動的に sphinx に含める方法はありませんが、利用可能なドキュメント オーサリング ツールの 1 つとして優れていると思います。より物語的なスタイルのドキュメントに最適です。ただし、phpdomain を使用すると、API ドキュメントも作成できます。
于 2011-09-10T01:56:08.237 に答える
2
PHP の ORM である Doctrine プロジェクトは、Sphinx を使用してwww.doctrine-project.orgにオンライン ドキュメントを生成します。彼らは、PHP 用のカスタム pygment を使用します。ドキュメントは、 https://github.com/doctrine/orm-documentationの Github で入手できます。カスタム PHP pygment css ファイルが含まれています。
また、python-pygmentsパッケージには、sphinx conf.py構成ファイルのpygments_style =値を変更することで試すことができる多くの pygment スタイルが付属してい ます。たとえば、python-pygments の一部であるパスティ ハイライトsytleを試すには、次のようにします。
pygments_sytle = 'pastie'
于 2011-08-24T19:20:40.540 に答える
0
私の知る限り、autodoc でサポートされている言語に制限されない限り、Sphinx ではほぼすべての構文を文書化できます。.. class、.. methodなどの標準の Sphinx ディレクティブを使用して、美しい API リファレンスを作成できます.. function。それらはソース コードとは別に完全に機能し、自動生成やソースへのリンクは必要ありません。
後で CSS にフックできる、いくつかの特別なクラスを使用して一般的な警告を作成することもできます。
.. admonition Title
:class: Ololo
This text could be formatted any way you want, using the ``Ololo`` tag.
元のディレクティブでは不十分な場合は、役割 (カスタム クラスも許可されます) や、特別な書式を使用してテキストを追加するその他の手段もあります。
ドキュメントをソース コードから非同期に作成する場合は、conf.pyプロジェクトの開始時または開始時に、コード カバレッジやその他のコード関連機能のチェックを無効にしてください。
PS:ここで、カスタム クラスを持つ要素に関する非常に優れた回答を確認できます。
于 2014-03-24T07:30:38.947 に答える