Sphinx FAQ
このセクションでは、Sphinxについてよく聞かれる質問とその答えについてまとめています。新しいセクションを気軽に追加してください！
どのようにすれば...
- ... LaTeXなしでPDFファイルを作成できますか？
- Sphinx統合機能が組み込まれている、 rst2pdf のバージョン 0.12以降を使用することができます。詳細は、 利用可能なビルダー のセクションをご覧下さい。
- ... セクション番号を設定できますか？
- LaTeX出力では自動的に設定されます。HTML出力では、 toctree ディレクティブに対して、ナンバリングをしたい位置に対して :numbered: オプションを付けると、設定することができます。
- ... ビルドするHTMLファイルの見た目をカスタマイズできますか？
- HTMLテーマのサポート を読んで、テーマを利用すると、カスタマイズすることができます。
- ... すべてのドキュメントで置換を行ったり、インクルードできますか？
- これらの定義を rst_epilog コンフィグ値を使って行ってください。
- ... すべての全体の目次をサイドバーに表示できますか？
- おそらく、 sidebartoc ブロックに、と想像しますが、カスタムのレイアウトテンプレートの中で、 toctree を呼び出して使用することが可能です。
- ... 自分用のSphinx拡張を作成できますか？
- Sphinx拡張チュートリアル をご覧ください。
- ... MoinMoinというWikiのマークアップで書かれた既存のドキュメントから変換できますか？
- 一番簡単の方法としてはレンダリング済みの xhtmlからreST に変換する方法でしょう。
見出しやコード例などがうまく変換できたとしても、クラスなどのマークアップはしなおす必要があるでしょう。
Sphinxと一緒に ... を使うには？
- Epydoc
- API ロール を提供するサードパーティ製の拡張機能があります。このロールは、与えられた識別子を持つ要素のEpydocのAPIドキュメントへの参照を行うことができます。
- Doxygen
- Michael Jones氏が reST/Sphinxからdoxygenへの橋渡しをする、 breathe というツールを開発しています。
- SCons
- Glenn Hutchings氏が、SphinxのドキュメントをビルドするためのSConsビルドスクリプトを作成しています。このスクリプトは、次のURLのところで開発されています: http://bitbucket.org/zondo/sphinx-scons
- PyPI
- Jannis Leidelが setuptoolsコマンド を作成しています。このコマンドを実行すると、自動的にSphinxで作られたドキュメントを、PyPIパッケージのドキュメント領域(http://packages.python.org/)にアップロードします。
- github pages
- Michael Jones氏の sphinx-to-githubツール を使用すると、SphinxのHTML出力を、githubページにアップロードする用に書き換えを行います。
- Google Analytics
次のようなカスタムの layout.html テンプレートを使用することができます:
{% extends "!layout.html" %}
{%- block extrahead %}
{{ super() }}
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'XXX アカウント番号 XXX']);
_gaq.push(['_trackPageview']);
</script>
{% endblock %}
{% block footer %}
{{ super() }}
<div class="footer">このページは統計情報を収集するために<a href="http://analytics.google.com/">
Google Analytics</a>を使用しています。もしも無効にしたい場合には、www.google-analytics.com
からロードされるJavaScriptをブロックして下さい。
<script type="text/javascript">
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ?
'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</div>
{% endblock %}
Epub情報
現在、epubビルダーはまだ実験的実装の段階です。まだSphinx本体のドキュメントでしかテストされていません。もしもepubファイルを生成したいのであれば、次の注意点をご覧になってください:
- テキストはいくつかのファイルに分割されます。長さの長いHTMLファイルの場合、電子ブックリーダーによってはレンダリングに長い時間がかかります。極端な場合には、1分ほどかかることもあります。
- マークアップは少なくなるようにしてください。これはレンダリング時間に関わってきます。
いくつかのリーダーでは、CSSの @font-face ディレクティブを使うことで、組み込みフォントや外部フォントを使用することができます。ソースコードのリストを表現する場合には、正しいマージンが行われるようになるため、 非常に これが役立ちます。デフォルトのCourierフォント(もしくはvariant)の場合には、一行につき60文字しか表現できません。もしもより狭いフォントを指定すると、一行の表示文字数を増やせます。 FontForge を使用して、フリーフォントの幅を短くしたバージョンを作成することができます。私が試した限りでは一行あたり70文字まで増やすことができました。
納得のいく結果を得るためには、多少の試行錯誤が必要になるでしょう。
- 大きなフローティング指定のdiv要素は適切に表示されません。もしも複数ページにわたるdiv要素があったとしても、最初のページにしか表示されません。もしこのような場合には、 sphinx/themes/epub/static/ にある epub.css をローカルの _static/ にコピーして、float設定を削除してください。
