Sphinx FAQ

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

どのようにすれば...

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

rinohtype provides a PDF builder that can be used as a drop-in replacement for the LaTeX builder.

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

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

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

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

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

Add them in the rst_prolog or rst_epilog config value.

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

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

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

See the Extension tutorials.

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

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

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

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

Read the Docs

Read the Docs is a documentation hosting service based around Sphinx. They will host sphinx documentation, along with supporting a number of other features including version support, PDF generation, and more. The Getting Started guide is a good place to start.

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 wrote a setuptools command that automatically uploads Sphinx documentation to the PyPI package documentation area at https://pythonhosted.org/.

GitHub Pages

Please add sphinx.ext.githubpages to your project. It allows you to publish your document in GitHub Pages. It generates helper files for GitHub Pages on building HTML document automatically.

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="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 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 %}
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.type = 'text/javascript';
             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.

Epub情報

epubファイルを作成するためのいくつかのヒントを記します。

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

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

  • For some readers you can use embedded or external fonts using the CSS @font-face directive. This is extremely useful for code listings which are often cut at the right margin. The default Courier font (or variant) is quite wide and you can only display up to 60 characters on a line. If you replace it with a narrower font, you can get more characters on a line. You may even use FontForge and create narrow variants of some free font. In my case I get up to 70 characters on a line.

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

  • Test the created epubs. You can use several alternatives. The ones I am aware of are Epubcheck, Calibre, FBreader (although it does not render the CSS), and Bookworm. For Bookworm, you can download the source from https://code.google.com/archive/p/threepress and run your own local server.

  • 大きなフローティング指定の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
    

    The kindlegen command doesn't accept documents that have section titles surrounding toctree directive:

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

    kindlegen assumes all documents order in line, but the resulting document has complicated order for kindlegen:

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

    If you get the following error, fix your document structure:

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