web-dev-qa-db-ja.com

誰かがSphinxを使用してC ++プロジェクトを文書化したことがありますか？

Sphinx はPython用の新しいドキュメントツールです。とても素敵に見えます。私が疑問に思っているのは：

  • これはC++プロジェクトの文書化にどの程度適していますか？
  • 既存のドキュメント（doxygenなど）をSphinx形式に変換するためのツールはありますか？
  • Sphinxを使用するC++プロジェクトのオンライン/ダウンロード可能な例はありますか？
  • Sphinxを使用したことのある人からのヒントはありますか？
pythondocumentationpython-sphinx
44
Nick

前述のように ここ および ここ 、

  • SphinxネイティブC++サポートは、コード内のドキュメント抽出ではなく、強調表示/フォーマット/参照に関連しています
  • breathe chrisdewが参照した議論から発展しました

[下に挿入された編集]：

私は、10個の異なるモジュール/ドメインで構成されるマルチ10k C++ライブラリでdoxygen + breathe + sphinxツールチェーンをテストしました。私の結論は次のとおりです。

  1. まだ完全には使用できません
  2. でも見続けて
  3. そして、最も重要なことは、あなたが現在あなたの時間に値する価値のあるOSSプロジェクトを探しているなら、あなた自身で時間を割くことを検討してください。

これらの点を詳しく説明します。

  1. 私は問題を抱えていました：

    • Doxygenマークアップ内のラテックスマークアップ（現在はサポートされていませんが、実装は簡単です）
    • いくつかのパーサーエラー（いくつかの関数ヘッダー定義）。これは、スフィンクスパーサーでエラーを引き起こすようですが、スフィンクスc ++コードブロックで直接テストしても問題ありません。修正の難しさについてはわかりませんが、これは深刻な機能ブレーカーです。
    • オーバーロードされた識別子に関するいくつかの問題。異なるクラスおよび/または名前空間および/またはdoxygenxml出力ファイルで同じ名前の関数をアドレス指定するためのいくつかのサポートがあるようです。しかし、単一のクラスで10個のオーバーロードされたコンストラクターの特定の1つを表示またはリンクすることは、実行不可能なATMのようです。参照/リンクの場合、呼吸が回避できる場合とできない場合があるスフィンクスレベルに並行して（おそらく一時的に）制限があります。
    • 現在、クラスのすべて（またはすべての保護/プライベート）メンバーを表示する方法はありません。これはどういうわけか別の修正で導入されたものであり、修復するのは本当に簡単なはずです。

    • より一般的な意味では、ATMはDoxygenのxml出力へのブリッジであることに注意してください。それは、上記の制限があるだけで、doxygenが行うことを正確に出力するような方法で理解されるべきではありません。むしろ、それはあなたに正確に、より多くではなく、より少なくではなく、

      • 1つのdoxygen出力ドメインのすべてを1つの巨大なページにダンプします
      • 特定の関数、メンバー、構造体、列挙型、typedef、またはクラスを表示しますが、これらは手動で指定する必要があります。 githubには、この全体的な概念上の問題に対処するかどうかわからないフォークがありますが、将来のヒントはありません。

  2. 私の意見では、完全に機能する呼吸は大きなギャップを埋め、かなり涼しい道を開くでしょう。したがって、潜在的な利益のためだけに見る価値があります。

  3. 残念ながら、クリエイターによるメンテナンスは今後大幅に低下するようです。したがって、会社で働いていて、上司に息が彼に合うと納得させることができる場合、または自由な時間があり、本当に価値のあるプロジェクトを探している場合は、フォークを与えることを検討してください！

最後のポインタとして、スフィンクスの doxylink contribプロジェクトにも注意してください。これは、中間ソリューションを提供する可能性があります。（cssスタイルに一致する）古いdoxygenドキュメントを参照する周囲のチュートリアルのような構造を構築します（i同じヘッダーをスフィンクスに挿入し、doxygenのドキュメントの上にルックアンドフィールを追加することもできると思います）。そうすれば、プロジェクトはスフィンクスとの親和性を維持し、呼吸が完全に行われると、ジャンプする準備が整います。しかし、繰り返しますが、それがあなたの議題に合うならば、いくらかの愛を呼吸することを示すことを考慮してください。

22
daspostloch

まず、sourceとbuildの2つのディレクトリツリーを保持します。 sourceをバージョン管理下に置きます。 buildをバージョン管理下に置かないでください。インストールの一部として再構築してください。

次に、 http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources を読んでください。

使用 sphinx-quickstart実践ドキュメントツリーを構築します。それがどのように機能するかを学ぶために数日間これで遊んでください。次に、それを再度使用して、SVNディレクトリに本物を構築します。

よく計画されたツリーにドキュメントを整理します。一部のセクションでは、そのセクションに「index.rst」が必要ですが、必要ないセクションもあります。セクションがどの程度「スタンドアロン」であるかによって異なります。

私たちのトップレベルindex.rstこのように見えます。

.. XXX documentation master file, created by sphinx-quickstart on Wed Dec 31 07:27:45 2008.

..  include:: overview.inc

.. _`requirements`:

Requirements
============

.. toctree::
   :maxdepth: 1

   requirements/requirements
   requirements/admin
   requirements/forward
   requirements/volume

.. _`architecture`:

Architecture
============

.. toctree::
   :maxdepth: 1

   architecture/architecture
   architecture/techstack
   architecture/webservice_tech
   architecture/webservice_Arch
   architecture/common_features
   architecture/linux_Host_architecture

Detailed Designs
================

..  toctree::
    :maxdepth: 3

    design/index


Installation and Operations
===========================

.. toctree::
   :maxdepth: 1

   deployment/installation
   deployment/operations
   deployment/support
   deployment/load_test_results
   deployment/reference
   deployment/licensing

Programming and API's
=====================

..  toctree::
    :maxdepth: 2

    programming/index

**API Reference**. The `API Reference`_ is generated from the source.

.. _`API Reference`: ../../../apidoc/xxx/index.html

..  note::
    The API reference must be built with `Epydoc`_.

    .. _`Epydoc`: http://epydoc.sourceforge.net/

Management
==========

.. toctree::
   :maxdepth: 2
   :glob:

   management/*


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

SVN Revision
============

::

    $Revision: 319 $

APIを「インクルード」するのではなく、通常のHTMLリンクで参照するだけであることに注意してください。

Sphinxには、automoduleと呼ばれる非常に優れたアドオンがあり、Pythonモジュールからdocstringを選択します。

UpdateSphinx 1.0以降、CおよびC++がサポートされています。 http://sphinx.pocoo.org/

11
S.Lott

XMLアプローチについては、 http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html をご覧ください。

4
fadedbee