Sphinx FAQ

このセクションでは、Sphinxについてよく聞かれる質問とその答えについてまとめています。新しいセクションを気軽に追加してください！

どのようにすれば...

... LaTeXなしでPDFファイルを作成できますか？

rinohtype はLaTeXビルダーの完全互換品として扱えるPDFビルダーを提供しています．

... セクション番号を設定できますか？

LaTeX出力では自動的に設定されます。HTML出力では、 toctree ディレクティブに対して、ナンバリングをしたい位置に対して :numbered: オプションを付けると、設定できます。

... ビルドするHTMLファイルの見た目をカスタマイズできますか？

HTML Theming を読んで、テーマを利用すると、カスタマイズできます。

... すべてのドキュメントで置換を行ったり、インクルードできますか？

これらの定義を rst_prolog`か、:confval:`rst_epilog のコンフィグ値を使って行ってください。

... すべての全体の目次をサイドバーに表示できますか？

おそらく、 sidebartoc ブロックに、と想像しますが、カスタムのレイアウトテンプレートの中で、 toctree を呼び出して使用することが可能です。

... 自分用のSphinx拡張を作成できますか？

See the 拡張機能のチュートリアル.

... MoinMoinというWikiのマークアップで書かれた既存のドキュメントから変換できますか？

一番簡単な方法としてはレンダリング済みの xhtmlからreST に変換する方法でしょう。 見出しやコード例などがうまく変換できたとしても、クラスなどのマークアップはしなおす必要があるでしょう。

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

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

Read the Docs

Read the Docs はSphinxを基盤としたドキュメントホスティングサービスです。バージョン管理、PDF作成など多くの機能を持ち、Sphinxドキュメントのサービスを提供しています。始めるには Getting Started のガイドをまず読むと良いでしょう。

Epydoc

API ロール を提供するサードパーティ製の拡張機能があります。このロールは、与えられた識別子を持つ要素のEpydocのAPIドキュメントを参照します。

Doxygen

Michael Jonesは reST/Sphinxをdoxygenに変換する breathe. を開発しています。

SCons

Glenn Hutchings has written a SCons build script to build Sphinx documentation; it is hosted here: https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel はSphinxドキュメントを https://pythonhosted.org/ というPyPIパッケージのドキュメントを置く場所に自動的にアップロードする setuptools command を作成しました。

GitHub Pages

sphinx.ext.githubpages をぜひご自身のプロジェクトに追加してください。GitHub Pagesでドキュメントをパブリッシュできるようになります。HTMドキュメントを自動ビルドする際には、GitHub Pages用のヘルパーファイル群を生成します。

MediaWiki

See sphinx-wiki, a project by Kevin Dunn.

Google Analytics

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

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script>
  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="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script>
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'https://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>
{% endblock %}

Google 検索

Sphinx のビルトインの検索機能をGoogle検索に置き換えるには、以下のようにしてください:

1. https://cse.google.com/cse/all に行き、Google検索のコードスニペットを作成してください。

2. そのコードスニペットをコピーし、ご自身のSphinxプロジェクト内の _templates/searchbox.html に貼り付けてください:

   <div>
      <h3>{{ _('Quick search') }}</h3>
      <script>
         (function() {
            var cx = '......';
            var gcse = document.createElement('script');
            gcse.async = true;
            gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
            var s = document.getElementsByTagName('script')[0];
            s.parentNode.insertBefore(gcse, s);
         })();
      </script>
     <gcse:search></gcse:search>
   </div>
   

3. Add searchbox.html to the html_sidebars configuration value.

Sphinx 対 Docutils

tl;dr: docutils はreStructuredText を多様なフォーマットに変換します。Sphinx は docutils 上で動作し、相互参照やインデックス化された文書の本体を構築します。

docutils はプレーンテキスト文書をより複雑な他のフォーマットへ変換する文書処理システムです。docutils documentation で触れたように、 docutilsでは readers をドキュメントの解読に用い、 parsers をプレーンテキストを様々な種類の nodes から構成された内部木表現へパースする際に用います。そして writers を用いてこの木を様々なドキュメントフォーマットに出力します。 docutils は1つのプレーンテキストフォーマット、すなわち reStructuredText パーサーのみを提供します。しかしながら、Sphinx's Markdown parser 1 などで 他の*out-of-tree* パーサーが実装されていて、これが様々なフォーマットに対するwriterを提供しています。対応するフォーマットとしてはHTML、LaTeX、 man pages、Open Document Format 、そしてXMLがあります。

docutils は各種の front-end tools を通してその機能を発揮します。例えば、 rst2html、rst2odt そして ``rst2xml``などです. ただし、これらすべてのツールや docutils 自体は文書を個々に扱います。相互参照や文書のインデックス化、あるいは文書の階層化（典型的な例で言えば、目次）はサポートされていません。

Sphinx はdocutils 上で動作し、 docutilsのreaderとパーサーを利用しながらもSphinx独自の Builders を提供します。その結果として、Sphinxは docutils の *writers*のいくつかをラップしています。このことにより、上で述べたようなdocutilsでは全くできなかったことが、Sphinxでは可能になっています。

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はフォントや色の表示がターミナルよりも優れており、(もちろん)様々なカスタマイズが可能です。

リンクの表示

Infoファイルの生成時の問題は、参照をどのように表示するか、です。もし、Infoファイルのソースを見ると、このセクションへのリンクは次のように書かれます:

* note Displaying Links: target-id

スタンドアローンの info リーダーの場合、参照はソースコードに表示されている通りに表示されます。一方Emacsの場合は、デフォルトで *note: は see に置換され、 target-id は非表示になります。例:

リンクの表示

One can disable generation of the inline references in a document with texinfo_cross_references. That makes an info file more readable with stand-alone reader (info).

Emacsで参照をどのように表示するかは、 Info-hide-note-references 変数の定義で変わります。もしこの変数に hide を設定すると、Emacsは *note: 部分と、 target-id の両方を非表示にします。もしこの制限を気にせず、リンクを多用してSphinxベースのドキュメントを見るのであれば、この設定がベストでしょう。しかし、この変数を変えた場合に、すべてのInfoドキュメントの表示と挙動が変わってしまうことに注意が必要です。

もし、Sphinxで作られたInfoファイルのときだけ、 Info-hide-note-references を hide にしたい場合には、次のEmacs Lispのコードをスタートアップファイル ~/.emacs.d/init.el に追加してください。

(defadvice info-insert-file-contents (after
                                      sphinx-info-insert-file-contents
                                      activate)
  "Hack to make `Info-hide-note-references' buffer-local and
automatically set to `hide' iff it can be determined that this file
was created from a Texinfo file generated by Docutils or Sphinx."
  (set (make-local-variable 'Info-hide-note-references)
       (default-value 'Info-hide-note-references))
  (save-excursion
    (save-restriction
      (widen) (goto-char (point-min))
      (when (re-search-forward
             "^Generated by \\(Sphinx\\|Docutils\\)"
             (save-excursion (search-forward "\x1f" nil t)) t)
        (set (make-local-variable 'Info-hide-note-references)
             'hide)))))

メモ

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

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

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

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

  info:Texinfo#makeinfo_options