25

過去にこのトピックに関するスレッドがいくつかあり、Sphinxはこれをまったくサポートしていないと主張しています。私は疑問を持っていましたが、それ以降に更新されているか、ドキュメントがかなり隠されていました。これは、Webサイトに別の方法で記載されているリンクがあるためです 。http ：//www.sphinx-doc.org/en/master/usage/ restructuredtext / domains.html＃cpp-domain

とにかく、私はSphinxを初めて使用しますが、Sphinxを使用して、ソースC++コードからのテキストを使用してドキュメントを（最終的に）自動化しようとしています。sphinx-apidoc -o ...これまでのところ、コマンドを使用するとどこにも到達できませんでした。ほぼ空白のドキュメントが作成されます。方法がわからないので、おそらく正しいディレクティブを使用していません-サポートドキュメントは私を助けることができませんでした。

誰かがそれを機能させるために必要な基本的な手順でいくつかの支援を提供できますか？C ++からドキュメントを自動生成できない場合、C ++ドメインは何のためにあり、それらをどのように使用するのですか？

4

1 に答える 1

43

C ++ドキュメントの自動生成について：

スフィンクスの使い方を読んだ後は、呼吸を調べる必要があります。

Breatheは、SphinxとDoxygenのドキュメントシステム間のブリッジを提供します。

Sphinxによって生成された一連のドキュメントにDoxygen情報を含めるのは簡単な方法です。目的は、Sphinxの使用を楽しんでいるが、Python以外の言語で作業する人々のためのサポートのようなautodocを作成することです。システムはDoxygenのxml出力に依存しています。

したがって、さらに、 Doxygenのコメントスタイルに従い、doxygenプロジェクトを設定する必要があります。しかし、私はそれを試しました、そしてそれは初期セットアップが行われた後に本当にうまくいきます。これは、スフィンクスとドキシゲンがどのように連携するかについてのアイデアを与える可能性のある私たちCMakeLists.txtの抜粋です：

macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
    add_custom_target(${TARGET_NAME}
    COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
        WORKING_DIRECTORY docs
        DEPENDS doxygen
        COMMENT ${COMMENT_STR}
    )

endmacro(add_sphinx_target)

add_custom_target(doxygen
    COMMAND doxygen docs/doxygen.conf
    COMMENT "Build doxygen xml files used by sphinx/breathe."
)

add_sphinx_target(docs-html
    html
    "Build html documentation"
)

したがって、初期設定後、基本的には次のようになります。

  1. でdoxygenドキュメントを作成するdoxygen path/to/config
  2. cdスフィンクス構成があるディレクトリに。
  3. でsphinxドキュメントをビルドするsphinx-build . path/to/output

C ++ドメインの場合：

Sphinxは、ドキュメントを自動生成するシステム以上の「ちょっとした」ものです。例をご覧になることをお勧めします（そして、スフィンクスのWebサイト自体がスフィンクスのreSTコードで記述されていることを考慮してください）。特に、Show Sourceスフィンクスで生成された多くのページのリンクをクリックしてください。

したがって、プロジェクトのドキュメントを自動的に生成できない場合は、自分で作成する必要があります。基本的に、sphinxは、あらゆる（LaTeX、HTML、…）コンパイラーに対するreSTです。したがって、任意のテキストを書くことができますが、さまざまな言語のソースコードを文書化するためのコマンドがたくさんあるという利点があります。各言語は、異なる言語の名前空間を分離するために独自のドメイン（プレフィックスまたは名前空間）を取得します。したがって、たとえば、次を使用してPython関数を文書化できます。

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
    Does something nasty with timers in repetition

（ソース）

私はcppドメインを使用して同じことを行うことができます：

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

（ソース）

したがって、doxygen +breatheを使用せずにsphinxを使用してc++プロジェクトを文書化する場合は、再構築されたテキストファイルを自分で作成する必要があります。これは、ドキュメントをソースコードから分割することも意味しますが、これは望ましくない場合があります。

私はそれが物事を少しクリアすることを願っています。さらに読むために、実際に何をするのかを理解するまで、スフィンクスのチュートリアルとドキュメントをよく読んでおくことを強くお勧めします。

于 2012-06-28T17:16:07.253 に答える