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は SConsのビルドスクリプトをSphinxドキュメントをビルドするために書きました。https://bitbucket.org/zondo/sphinx-scons にあります。

PyPI

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

GitHub Pages

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

MediaWiki

Kevin Dunnによるプロジェクトです。https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home を見てください。

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' : 'http://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 converts reStructuredText to multiple output formats. Sphinx builds upon docutils to allow construction of cross-referenced and indexed bodies of documentation.

docutils is a text processing system for converting plain text documentation into other, richer formats. As noted in the docutils documentation, docutils uses readers to read a document, parsers for parsing plain text formats into an internal tree representation made up of different types of nodes, and writers to output this tree in various document formats. docutils provides parsers for one plain text format - reStructuredText - though other, out-of-tree parsers have been implemented including Sphinx's Markdown parser. On the other hand, it provides writers for many different formats including HTML, LaTeX, man pages, Open Document Format and XML.

docutils exposes all of its functionality through a variety of front-end tools, such as rst2html, rst2odt and rst2xml. Crucially though, all of these tools, and docutils itself, are concerned with individual documents. They don't support concepts such as cross-referencing, indexing of documents, or the construction of a document hierarchy (typically manifesting in a table of contents).

Sphinx builds upon docutils by harnessing docutils' readers and parsers and providing its own Builders. As a result, Sphinx wraps some of the writers provided by docutils. This allows Sphinx to provide many features that would simply not be possible with docutils, such as those outlined above.

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,_,_
    """}