Sphinxは、Python 用の新しいドキュメント ツールです。とても素敵に見えます。私が疑問に思っているのは：
- これは C++ プロジェクトの文書化にどの程度適していますか?
- 既存のドキュメント (doxygen など) を Sphinx 形式に変換するツールはありますか?
- Sphinx を使用する C++ プロジェクトのオンライン/ダウンロード可能な例はありますか?
- Sphinx を使用したことがある人からのヒントはありますか?
19883 次
3 に答える
23
- SphinxネイティブC++サポートは、コード内のドキュメント抽出ではなく、強調表示/フォーマット/参照に関連しています
- ブレスは、クリスデューが言及した議論から発展しました
[下に挿入された編集]：
10個の異なるモジュール/ドメインで構成されるマルチ10kC++ライブラリでdoxygen+breathe+sphinxツールチェーンをテストしました。私の結論は次のとおりです。
- まだ完全には使用できません
- でも見続けて
- そして、最も重要なことは、あなたが現在あなたの時間に値する価値のあるOSSプロジェクトを探しているなら、あなた自身で時間を割くことを検討してください。
これらの点を詳しく説明します。
私は問題を抱えていました：
- doxygenマークアップ内のラテックスマークアップ（現在はサポートされていませんが、実装は簡単です）
- いくつかのパーサーエラー（いくつかの関数ヘッダー定義）。これは、スフィンクスパーサーでエラーを引き起こすように見えますが、スフィンクスc++コードブロックで直接テストしても問題ありません。修正の難しさについてはわかりませんが、これは深刻な機能ブレーカーです。
- オーバーロードされた識別子に関するいくつかの問題。異なるクラスや名前空間、および/またはdoxygenxml出力ファイルで同じ名前の関数をアドレス指定するためのサポートがあるようです。しかし、単一のクラスでオーバーロードされた10個のコンストラクターの1つを表示したり、それらにリンクしたりすることは、ATMでは実行不可能のようです。参照/リンクの場合、呼吸が回避できる場合とできない場合があるスフィンクスレベルに並行して（おそらく一時的に）制限があります。
- 現在、クラスのすべて（またはすべての保護/プライベート）メンバーを表示する方法はありません。これはどういうわけか別の修正で導入されたものであり、修復するのは本当に簡単なはずです。
より一般的な意味では、ATMはDoxygenのxml出力へのブリッジであることに注意してください。それは、上記の制限があるだけで、doxygenが行うことを正確に出力するような方法で理解されるべきではありません。むしろ、それはあなたに正確に、より多くではなく、より少なくではなく、
- 1つのdoxygen出力ドメインのすべてを1つの巨大なページにダンプします
- 特定の関数、メンバー、構造体、列挙型、typedef、またはクラスを表示します。ただし、これらは手動で指定する必要があります。githubには、この全体的な概念上の問題に対処するかどうかわからないフォークがありますが、将来のヒントはありません。
私の意見では、完全に機能する呼吸は大きなギャップを埋め、かなりクールな道を開くでしょう。したがって、潜在的な利益のためだけに見る価値があります。
残念ながら、クリエーターによるメンテナンスは今後大幅に低下するようです。したがって、会社で働いていて、上司に息をのむように説得できる場合、または自由な時間があり、本当に価値のあるプロジェクトを探している場合は、それをフォークすることを検討してください！
最後の指針として、スフィンクスのdoxylink contribプロジェクトにも注意してください。これは、中間的な解決策を提供する可能性があります。（cssスタイルに一致する）古いdoxygenドキュメントを参照する周囲のチュートリアルのような構造を構築します（同じものを注入することもできると思います）スフィンクスへのヘッダーとdoxygenドキュメントの上にあるlook'n'feels）。そうすることで、プロジェクトはスフィンクスとの親和性を維持し、呼吸が完全に行われると、ジャンプする準備が整います。しかし、繰り返しになりますが、それがあなたの議題に合うなら、いくつかの愛を呼吸することを示すことを検討してください。
于 2011-02-15T14:57:01.297 に答える
11
まず、2 つのディレクトリ ツリーsourceとbuild. 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 を選択します。
更新Sphinx 1.0 では、C と C++ がサポートされています。 http://sphinx.pocoo.org/
于 2009-05-07T15:01:29.740 に答える
4
XML アプローチについては、http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.htmlをご覧ください。
于 2009-10-29T15:52:57.040 に答える