問題タブ [python-sphinx]

で見つけました

http://svn.python.org/projects/doctools/trunk/sphinx/locale

Sphinx で使用できるいくつかの言語をサポートしていますが、インストール方法の説明が見つかりませんでした: どのファイルをどのディレクトリにダウンロードしてインストールする必要がありますか?

ヒントをいただければ幸いです。

現在、既存の (不完全な) ドキュメントをすべてSphinxに移行しています。

問題は、ドキュメンテーションがPython docstringを使用しており(モジュールは C で書かれていますが、おそらく問題にはなりません)、クラスのドキュメンテーションを Sphinx で使用できる形式に変換する必要があることです。

sphinx.ext.autodocがありますが、現在のドキュメント文字列をドキュメントに自動的に配置します。現在のdocstringに基づいて（ RST ）でソースファイルを生成したいので、手動で編集および改善できます。

docstring を Sphinx の RST に変換するにはどうすればよいですか?

Sphinxで処理される RST を記述しているときに、図を参照するときに Sphinx LaTeX 出力で図番号を使用することができません。たとえば、次のコード:

これに変換されます：

They're come!に見られるように、レミングが攻撃しています。

/ここに画像が入ります/

図 1.1: 彼らが来る!

しかし、私が欲しいのは、次のような図を参照する「標準的な」LaTeX の方法です。

図 1.1 に見られるように、レミングが攻撃しています。

どうすればこれを達成できますか? 私が現在使用しているコードは、Sphinx のマニュアルで推奨されているものですが、必要な出力が得られません。

PDF および HTML ヘルプ生成をサポートしているため、現在、ソフトウェア プロジェクトの文書化にAsciiDocを使用しています。現在、 a2x ツールチェーンが適切に機能するように、Cygwin で実行しています。これは私にとってはうまくいきますが、他の Windows コンピューターでセットアップするのは面倒です。私は別の方法を探していて、最近 Sphinx を再訪しました。HTML ヘルプ ファイルが生成されるようになったので、試してみましたが、実行した小規模なテストではうまく機能するようです。

私の質問は、Windows プログラムが適切なヘルプ API を呼び出すことができ、ファイルが起動され、目的の場所に開かれるように、コンテキスト依存ヘルプのマップ ID をテキストで指定する方法はありますか?

AsciiDoc では を使用してpass::[<?dbhh topicname="_about" topicid="801"?>]います。これらの構造を使用することにより、context.hおよびが他の HTML ヘルプ ファイル (状況依存のヘルプ情報alias.h)と共に生成されます。

Sphinx を使用して、Python で 5,000 行以上のプロジェクトを文書化しようとしています。約 7 つの基本モジュールがあります。私の知る限り、autodoc を使用するには、プロジェクト内の各ファイルに対して次のようなコードを記述する必要があります。

私は多くのファイルを持っているので、これは面倒です。「mods」パッケージを文書化することを指定できれば、はるかに簡単になります。その後、Sphinx はパッケージを再帰的に調べて、各サブモジュールのページを作成できます。

このような機能はありますか？そうでない場合は、すべての .rst ファイルを作成するスクリプトを作成できますが、それには多くの時間がかかります。

今回は Linux に Sphinx を実装したいと思います。同じことを行うために必要なAPIを教えてください。そうしないと、関連するリンクも実行されます。PHP の場合はたくさん見つかりましたが、C++ の場合は見つかりませんでした。

アプリケーションで GTKmm も使用しました。

私は Sphinx を学んでいて、ReST ファイルを編集する必要があります。そのためのインテリジェントなエディターはありますか? 同様に、コードの色付け、簡単なインデント、コード補完 (できれば) などを提供してくれるエディターです。

Sphinx が私のクラスの Translation を気に入らないのではないかと、ひそかに疑っています。自動メソッドを実行しようとすると:

次の警告が表示されます。

パスなどは正しいです。Translation を conf.py に直接インポートしようとしましたが、同様の問題がありました。次のようなことを試したとき、まだ問題がありました。

from translations.models import Translation as t

インポートはできましたが、Translation 内でインポートすると、最終的に Sphinx が同じエラーを返しました。

問題のドキュメントは次のとおりです。

ザンボニ ドキュメンテーション

Sphinx 0.6.5 を使用して作成されました。

Python のドキュメントで が使用されていることは知っていますが、 や などreStructuredTextのセクションが異なります。http://docs.python.org/whatsnew/2.6.htmlhttp://docs.python.org/tutorial/index.html

reStructuredText でこれをどのように行いますか? rst2htmlその構造を維持しながら、多数のディレクトリで実行していますか?

Sphinx を使用していることは知っていますが ( Thomas Wouters の回答で直接 rst2html ではありません)、リポジトリ内のソース コード ファイルを使用して最初の構造をどのように整理すれば、本格的な自動化されたドキュメント Web サイトを作成できますか?

私は doctests が大好きです。これは私が使用する唯一のテスト フレームワークです。なぜなら、書くのがとても速いからです。また、sphinx と一緒に使用すると、ほとんど労力をかけずに素晴らしいドキュメントを作成できます...

ただし、非常に多くの場合、次のようなことをしてしまいます。

つまり、すべてのテストとドキュメントの説明をモジュールの一番上に置いているので、実際のコードを見つけるには愚かにもスクロールする必要があり、これはかなり醜いです (私の意見では)。ただし、ソース コードを読みながら doctests を読むことができるはずなので、doctests はモジュールに残すべきだと思います。ここで私の質問があります: sphinx/doctests 愛好家の皆さん、コードの可読性が損なわれないように、どのように doctests を編成しますか? doctests や sphinx のスタイルガイドはありますか? スフィンクスを使用したドキュメント文字列の場合、Google またはスフィンクス スタイル ガイドなどを使用しますか?