Sphinx FAQ¶

これは Sphinx に関するよくある質問のリストです。新しい項目を提案してください！

どうすれば…¶

… LaTeX なしで PDF ファイルを作成できますか?: rinohtype は、LaTeX ビルダーのドロップイン代替として使用できる PDF ビルダーを提供します。
… セクション番号を取得できますか?: LaTeX 出力では自動的に設定されます。HTML の場合は、番号を付け始める場所に :numbered: オプションを toctree ディレクティブに指定してください。
… ビルドされた HTML ファイルの外観をカスタマイズできますか?: テーマを使用します。 HTML のテーマ設定を参照してください。
… グローバルな置換またはインクルードを追加できますか?: それらを rst_prolog または rst_epilog 設定値に追加します。
… サイドバーに TOC ツリー全体を表示できますか?: カスタムレイアウトテンプレート、おそらく sidebartoc ブロックで toctree 呼び出し可能オブジェクトを使用します。
… 独自の拡張機能を記述できますか?: チュートリアルを参照してください。
… 既存の MoinMoin マークアップを使用したドキュメントから変換できますか?: 最も簡単な方法は xhtml に変換してから、xhtml を reStructuredText に変換することです。クラスなどをマークアップする必要はありますが、見出しとコード例はきれいに変換できます。

さらに多くの拡張機能やその他のコントリビューションについては、sphinx-contrib リポジトリを参照してください。

Sphinxと…の連携¶

Read the Docs

Read the Docs は、Sphinx を中心としたドキュメントホスティングサービスです。Sphinx ドキュメントをホストするだけでなく、バージョンサポート、PDF 生成など、さまざまな機能もサポートしています。はじめにガイドは、始めるのに最適な場所です。

Epydoc

特定の識別子の Epydoc の API ドキュメントを参照する api ロールを提供するサードパーティの拡張機能があります。

Doxygen

Michael Jones は、doxygen への reStructuredText/Sphinx ブリッジである breathe を開発しました。

SCons

Glenn Hutchings は、Sphinx ドキュメントをビルドする SCons ビルドスクリプトを作成しました。これはこちらでホストされています: https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel は、Sphinx ドキュメントを https://pythonhosted.org/ の PyPI パッケージドキュメント領域に自動的にアップロードする setuptools コマンドを作成しました。

GitHub Pages

sphinx.ext.githubpages をプロジェクトに追加してください。これにより、GitHub Pages でドキュメントを公開できます。HTML ドキュメントのビルド時に GitHub Pages 用のヘルパーファイルが自動的に生成されます。

MediaWiki

Kevin Dunn によるプロジェクトである sphinx-wiki を参照してください。

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 検索に置き換えるには、次の手順に従ってください。

https://cse.google.com/cse/all にアクセスして、Google 検索コードスニペットを作成します。

コードスニペットをコピーして、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>

html_sidebars 設定値に searchbox.html を追加します。

Sphinx vs. Docutils¶

要するに: docutils は reStructuredText を複数の出力形式に変換します。Sphinx は docutils を基盤として、相互参照された索引付きのドキュメント本体を構築できるようにします。

docutils は、プレーンテキストのドキュメントを他のよりリッチな形式に変換するためのテキスト処理システムです。docutils ドキュメントで述べられているように、docutils はドキュメントを読み取る *reader*、プレーンテキスト形式をさまざまな種類の *ノード* で構成される内部ツリー表現に解析する *パーサー*、およびこのツリーをさまざまなドキュメント形式で出力する *ライター* を使用します。docutils は、1 つのプレーンテキスト形式である reStructuredText 用のパーサーを提供しますが、Sphinx の Markdown パーサーを含む他の *アウトオブツリー* パーサーも実装されています。一方、HTML、LaTeX、man ページ、Open Document Format、XML など、さまざまな形式のライターを提供します。

docutils は、rst2html、rst2odt、rst2xml など、さまざまなフロントエンドツールを介してすべての機能を提供します。ただし、これらのツールと docutils 自体は、すべて個別のドキュメントに関係しています。相互参照、ドキュメントの索引付け、またはドキュメント階層の構築 (通常、目次に表れます) などの概念はサポートしていません。

Sphinx は、docutils のリーダーとパーサーを利用し、独自のビルダーを提供することで、docutils を基盤としています。その結果、Sphinx は docutils によって提供される *ライター* の一部をラップします。これにより、Sphinx は上記のような docutils では不可能な多くの機能を提供できます。

Epub情報¶

次のリストは、epub ファイルの作成に関するいくつかのヒントを示しています

テキストをいくつかのファイルに分割します。個々の HTML ファイルが長ければ長いほど、電子書籍リーダーでのレンダリングに時間がかかります。極端な場合、レンダリングに 1 分もかかることがあります。
マークアップを最小限に抑えてください。これもレンダリング時間で効果を発揮します。
一部のリーダーでは、CSS @font-face ディレクティブを使用して、埋め込みフォントまたは外部フォントを使用できます。これは、右マージンで切り取られることが多いコードリストにとって *非常に* 役立ちます。デフォルトの Courier フォント (またはバリアント) は非常に幅広く、1 行あたり最大 60 文字しか表示できません。これをより狭いフォントに置き換えると、1 行に表示できる文字数が増えます。FontForge を使用して、一部のフリーフォントの狭いバリアントを作成することもできます。私の場合、1 行あたり最大 70 文字表示できます。

妥当な結果が得られるまで、少し実験する必要があるかもしれません。
作成された epub をテストします。いくつかの代替手段を使用できます。私が知っているのは、Epubcheck、Calibre、FBreader (ただし、CSS はレンダリングしません)、および Bookworm です。Bookworm の場合、ソースを https://code.google.com/archive/p/threepress からダウンロードして、独自のローカルサーバーを実行できます。
大きなフローティング div は正しく表示されません。複数のページにまたがっている場合、div は最初のページにのみ表示されます。その場合は、epub.css を sphinx/themes/epub/static/ ディレクトリからローカルの _static/ ディレクトリにコピーして、float 設定を削除できます。
toctree ディレクティブの外側に挿入されたファイルは、手動で含める必要があります。これは、付録 (たとえば、用語集や索引) に適用される場合があります。epub_post_files オプションを使用して追加できます。
epub カバーページの処理は、イメージパスを自動的に解決し、イメージを _images ディレクトリに入れる reStructuredText の手順とは異なります。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 ファイルで遭遇する可能性のある顕著な問題の 1 つは、参照の表示方法です。Info ファイルのソースを読むと、このセクションへの参照は次のようになります。

* note Displaying Links: target-id

スタンドアロンのリーダーである info では、参照はソースに表示されるとおりに表示されます。一方、Emacs はデフォルトで *note: を see に置き換え、target-id を隠します。たとえば、

リンクの表示

ドキュメント内のインライン参照の生成は、texinfo_cross_references で無効にできます。これにより、スタンドアロンリーダー (info) で Info ファイルがより読みやすくなります。

Emacs が参照をどのように表示するかという正確な動作は、変数 Info-hide-note-references に依存します。値が hide に設定されている場合、Emacs は *note: 部分と target-id の両方を隠します。これは、Sphinx ベースのドキュメントはリンクを頻繁に使用し、この制限を考慮に入れていないことが多いため、一般的に最適な表示方法です。ただし、この変数を変更すると、すべての Info ドキュメントの表示方法に影響し、ほとんどのドキュメントはこの動作を考慮に入れています。

Emacs で Sphinx によって生成された Info ファイルを Info-hide-note-references に値 hide を使用して表示し、他のすべての Info ファイルにはデフォルト値を使用したい場合は、次の 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 ファイルへのリンクは、やや正式な URI スキーム info を使用して作成できます。たとえば、
```
info:Texinfo#makeinfo_options
```