.. _faq:

Sphinx FAQ
==========

.. This is a list of Frequently Asked Questions about Sphinx.  Feel free to
   suggest new entries!

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

どのようにすれば...
-------------------

.. How do I...
   -----------

.. ... get section numbers?
       They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
       the :dir:`toctree` directive where you want to start numbering.

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

.. ... customize the look of the built HTML files?
       Use themes, see :doc:`theming`.

... ビルドするHTMLファイルの見た目をカスタマイズできますか？
   :doc:`theming` を読んで、テーマを利用すると、カスタマイズすることができます。

.. ... add global substitutions or includes?
       Add them in the :confval:`rst_epilog` config value.

... すべてのドキュメントで置換を行ったり、インクルードできますか？
   これらの定義を :confval:`rst_epilog` コンフィグ値を使って行ってください。

.. ... write my own extension?
      See the :ref:`extension tutorial <exttut>`.

... 自分用のSphinx拡張を作成できますか？
   :ref:`Sphinx拡張チュートリアル <exttut>` をご覧ください。

.. ... convert from my existing docs using MoinMoin markup?
      The easiest way is to convert to xhtml, then convert `xhtml to reST`_.  You'll
      still need to mark up classes and such, but the headings and code examples
      come through cleanly.

... MoinMoinというWikiのマークアップで書かれた既存のドキュメントから変換できますか？
   一番簡単の方法としてはレンダリング済みの `xhtmlからreST`_ に変換する方法でしょう。 
   見出しやコード例などがうまく変換できたとしても、クラスなどのマークアップはしなおす必要があるでしょう。

.. Using Sphinx with...
   --------------------

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

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

.. There's a third-party extension providing an `api role`_ which refers to
   Epydoc's API docs for a given identifier.

Doxygen

   Michael Jones氏が reST/Sphinxからdoxygenへの橋渡しをする、 `breathe  <http://github.com/michaeljones/breathe/tree/master>`_ というツールを開発しています。

.. Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
   <http://github.com/michaeljones/breathe/tree/master>`_.

SCons
   Glenn Hutchings氏が、SphinxのドキュメントをビルドするためのSConsビルドスクリプトを作成しています。このスクリプトは、次のURLのところで開発されています: http://bitbucket.org/zondo/sphinx-scons

.. Glenn Hutchings has written a SCons build script to build Sphinx
   documentation; it is hosted here: http://bitbucket.org/zondo/sphinx-scons

github pages
   Michael Jones氏の `sphinx-to-githubツール <http://github.com/michaeljones/sphinx-to-github/tree/master>`_ を使用すると、SphinxのHTML出力を、githubページにアップロードする用に書き換えを行います。

.. You can use `Michael Jones' sphinx-to-github tool 
   <http://github.com/michaeljones/sphinx-to-github/tree/master>`_ to prepare
   Sphinx HTML output.

.. _API ロール: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
.. _xhtmlからreST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py


.. 
   .. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
   .. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py