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 documentsでHTMLを作成できますか?
https://github.com/nyergler/hieroglyph の “Hieroglyph” パッケージを参照してください。

他にも多くの有志により提供された拡張機能があるので、sphinx-contrib リポジトリを参照してください。

Sphinxと一緒に ... を使うには?

Read the Docs
https://readthedocs.org はSphinxを基盤としたドキュメントホスティングサービスです。バージョン管理、PDF作成など多くの機能を持ち、Sphinxドキュメントのサービスを提供しています。始めるには Getting Started をまず読むと良いでしょう。
Epydoc
API ロール を提供するサードパーティ製の拡張機能があります。このロールは、与えられた識別子を持つ要素のEpydocのAPIドキュメントを参照します。
Doxygen
Michael Jonesは reST/Sphinxをdoxygenに変換する breathe. を開発しています。
SCons
Glenn Hutchingsは SConsのビルドスクリプトをSphinxドキュメントをビルドするために書きました。https://bitbucket.org/zondo/sphinx-scons にあります。
PyPI
Jannis Leidel はSphinxドキュメントを http://pythonhosted.org/ というPyPIパッケージのドキュメントを置く場所に自動的にアップロードする setuptools command を作成しました。
GitHub Pages
デフォルトでは、Sphinxが静的ファイルを置いているような、アンダースコアで始まるディレクトリは無視されます。SphinxのHTML出力を置くために、GitHubのプリプロセッサを 無効にする ことができます。
MediaWiki
Kevin Dunnによるプロジェクトです。https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home を見てください。
Google Analytics

次のようなカスタムの layout.html テンプレートを使用できます:

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'XXX account number XXX']);
  _gaq.push(['_trackPageview']);
</script>
{% endblock %}

{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="http://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<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ファイルを作成するためのいくつかのヒントを記します。

  • テキストはいくつかのファイルに分割してください。長いHTMLファイルの場合、電子ブックリーダーによってはレンダリングに長い時間がかかります。極端な場合には、1分ほどかかることもあります。

  • マークアップは少なくなるようにしてください。これはレンダリング時間に関わってきます。

  • いくつかの電子書籍リーダーでは、CSSの @font-face ディレクティブを使うことで、組み込みフォントや外部フォントを使用できます。正しいマージンが行われるようになるため、ソースコードのリストを表現する場合に 非常に 役立ちます。デフォルトのCourierフォント(もしくはvariant)の場合には、一行につき60文字しか表現できません。もしもより狭いフォントを指定すると、一行の表示文字数を増やせます。 FontForge を使用して、フリーフォントの幅を短くしたバージョンを作成することができます。私が試した限りでは一行あたり70文字まで増やすことができました。

    納得のいく結果を得るためには、多少の試行錯誤が必要になるでしょう。

  • 作成されたepubファイルはテストしてください。いくつかの選択肢があります。私が確認するようにしているのは、 Epubcheck, Calibre, FBreader (これはCSSをレンダリングできません), Bookworm です。Bookwormは、 https://code.google.com/archive/p/threepress からダウンロードして、ローカルのサーバ上で実行します。

  • 大きなフローティング指定のdiv要素は適切に表示されません。もしも複数ページにわたるdiv要素があったとしても、最初のページにしか表示されません。もしこのような場合には、 sphinx/themes/epub/static/ にある epub.css をローカルの _static/ にコピーして、float設定を削除してください。

  • toctree ディレクティブ外のファイルは、手動で含めなければなりません。用語集、索引などのAppendixが場合によっては該当します。 epub_post_files オプションを使うと、これらのファイルを追加できます。

  • epubカバーページの扱いは、自動的に画像パスを解析し、 _images ディレクトリに画像を置いてくれる他のreStructedTextの方式とは異なります。epubカバーページでは、画像を html_static_path ディレクトリに置いた上で、 epub_cover 設定に完全なパスを書く必要があります。

  • kindlegen コマンドは、 epub3 の生成ファイルをKindle用の .mobi ファイルに変換できます。 次のコマンドを入力することで _build/epub 下に yourdoc.mobi が得られます。

    $ make epub
    $ kindlegen _build/epub/yourdoc.epub
    

    kindlegen コマンドは、toctree ディレクティブがセクションタイトルで囲まれているドキュメントを受け付けません:

    Section Title
    =============
    
    .. toctree::
    
       subdocument
    
    Section After Toc Tree
    ======================
    

    kindlegenではすべてのドキュメントが一列の順に並んでいることを想定していますが、出力されたドキュメントの並びはkindlegenにとって理解しにくいことがあります:

    ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
    

    下記のエラーが出たら、ドキュメントの構造を修正してください:

    Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
    Error(prcgen):E24001: The table of content could not be built.
    

Texinfo情報

Infoファイルを読むプログラムは、 info とGNU Emacsの2つあります。 info プログラムは機能は少ないのですが、ほとんどのUNIX環境で利用可能であり、ターミナルからのアクセスは簡単です。Emacsはフォントや色の表示がターミナルよりも優れており、(もちろん)様々なカスタマイズが可能です。

メモ

以下のメモは、Texinfoファイルを作る時の参考となるメモです。

  • それぞれのセクションは、Infoファイルの node となります。

  • メニューエントリーとxrefの中のコロン(:)はきちんとエスケープされません。これはセミコロン(;)にと変換されます。

  • 外部のInfoファイルへの参照は、 info という公式なURIスキームを使用して作成されます。例えば:

    info:Texinfo#makeinfo_options
    
  • インラインマークアップ

    マークアップパラメーター名と他の値とで使われるため、標準フォーマットの *strong*_emphasis_ の出力は曖昧となります。これは非常によく見られる習慣のため、デフォルトのフォーマットが変更され、 emphasisstrongliteral と同じように表示されるようになりました。

    標準フォーマットは以下の設定を conf.py に付け加えることで再度有効になります。:

    texinfo_elements = {'preamble': """
    @definfoenclose strong,*,*
    @definfoenclose emph,_,_
    """}