Sphinx

概要:美しいドキュメントを簡単に生成することができるドキュメンテーションツール

conf.py

HTML で使用できるテーマ(html_theme)

使用可能な名前一覧について
タイトル 詳細
conf.py html_theme = ‘default’
sphinx ディレクトリーから 例) \Portable Python 2.7.5.1\App\Lib\site-packages\sphinx-1.2.1-py2.7.egg\sphinx\themes
ウェブサイト

シンタックスハイライト(pygments_style)

使用可能な名前一覧について
タイトル 詳細
conf.py pygments_style = ‘sphinx’
pygments ディレクトリーから 例) \Portable Python 2.7.5.1\App\Lib\site-packages\Pygments-1.6-py2.7.egg\pygments\styles
サンプル Preview all Pygments Styles for your code highlighting needs

reStructuredText

テーブル

Excelファイルの表を取り込みたい場合

Excelファイルから対象の範囲をコピーして、 ウェブツール: TSV2HTML Table のインプットに張り付けて、 HTMLに変換する。 結合セルとかある場合は、適当にWYSIWYGとかで微調整。

.. raw:: html
   :file: ../_static/sample.html

※拡張したい場合、 SphinxをCSSとJavaScript(jQuery)で拡張するテーブル(table)を拡張する を参照


.. code-block:: や .. literalinclude::の:language:で使える名前

.. code-block:: や .. literalinclude::の:language:で使える名前
タイトル 詳細
ウェブサイト
Pygments ディレクトリーから 例) \Portable Python 2.7.5.1\App\Lib\site-packages\Pygments-1.6-py2.7.egg\pygments\lexers\_mapping.py
Python $ python -c “import pprint, pygments.lexers; pprint.pprint(list(pygments.lexers.get_all_lexers()))”

国際化 internationalization(i18n)

*.potファイルの作成

> make gettext

_build\locale

*.poファイルの作成

詳細は Code::Blocks非公式に国際化(i18n)手順(gettext) を参照

*.poファイルの配置

locale\ja\LC_MESSAGES

conf.pyファイルの設定

language = 'ja'
locale_dirs = ['locale/']

htmlファイルの生成

> make html

TODO: Sphinx 1.2.2

Sphinx 1.2.2
概要 詳細
/開始のパスを使いたい
.. raw:: html
   :file: ../test.html
上下のナビゲーション(rellink)が英語になる
language = ‘ja’の設定にて、
名前が sphinx のサブディレクトリーを含んだプロジェクトでhtmlを作成すると、
上下のナビゲーション(rellink)が英語になる(バグ?)
検索結果が英語
language = ‘ja’の設定にて、search.htmlの文言が英語
sphinx/themes/basic/static/searchtools.js_t
_static配下の不要ファイル
html_theme = ‘default’の設定にて、
websupport.js, sidebar.js, *.pngなど不要なファイルが生成される。
../_staticへのリンクがexternal
externalだがinternalにしたい。
<a class=”reference external” href=”../_static/a.html”>あ</a>
アンカーにnofllowを指定したい <a rel=”nofllow” href=”#”>あ</a>
サイトマップ を自動生成したい sitemap.xml
生成するhtmlの更新日時 rstの更新日時と同じにしたい(もしくはrstファイルに更新日時を埋め込みたい。)
genindex.html と search.html のメタタグを制御したい
_templates/layout.html

<head>
{%- if “#” == pathto(‘genindex’) %}
<meta name=”robots” content=”noindex” />
{%- endif %}
{%- if “#” == pathto(‘search’) %}
<meta name=”robots” content=”noindex, nofollow, noarchive” />
{%- endif %}

Sphinx 1.2.2 (デフォルトテーマ)
概要 詳細
<html>の
xml:lang=”ja”
lang=”ja”
に対応したい

sphinx/builders/html.py

 def prepare_writing(self, docnames):
     self.globalcontext = dict(
         ...
         language = self.config.language, # add
     )

sphinx/themes/basic/layout.html

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{{ language }}" lang="{{ language }}"></html>
localtoc.html
の空の<ul />
/themes/basic/localtoc.html の {{ toc }} が空の<ul></ul>を作成してしまう。
“/> 問題
(<br/> -> <br />)
検索条件 [“/>]
フォルダ /sphinx/themes
agogolayout.html(18,81): <img class=”logo” src=”{{ pathto(‘_static/’ + logo, 1) }}” alt=”Logo”/>
basiclayout.html(55,83): <img class=”logo” src=”{{ pathto(‘_static/’ + logo, 1) }}” alt=”Logo”/>
basiclayout.html(123,58): href=”{{ pathto(‘_static/opensearch.xml’, 1) }}”/>
basiclayout.html(126,74): <link rel=”shortcut icon” href=”{{ pathto(‘_static/’ + favicon, 1) }}”/>
basicopensearch.xml(7,117): template=”{{ use_opensearch }}/{{ pathto(‘search’) }}?q={searchTerms}&amp;check_keywords=yes&amp;area=default”/>
basicstaticsearchtools.js_t(122,39): this.output = $(‘<ul class=”search”/>’).appendTo(this.out);
haikulayout.html(39,79): <img class=”logo” src=”{{ pathto(‘_static/’ + logo, 1) }}” alt=”Logo”/>
haikulayout.html(43,84): <img class=”rightlogo” src=”{{ pathto(‘_static/’ + logo, 1) }}” alt=”Logo”/>
pyramidlayout.html(16,75): <img class=”logo” src=”{{ pathto(‘_static/’ + logo, 1) }}” alt=”Logo”/>

Pygments 1.6
概要 詳細
任意のコードハイライトを使いたい  
diffファイルのコードハイライト表示がしたい diffファイルを読み込んで、左右に見やすく表示したい
code-block の空白行
.. code-block:: rst
  :emphasize-lines: 1

   a
   この行を空白行にした場合、空白行が表示されない(IE9)
   b
 a

 b
C++11 のキーワードがたりない

\Portable Python 2.7.5.1\App\Lib\site-packages\Pygments-1.6-py2.7.egg\pygments\lexers\compiled.py

 class CppLexer(CFamilyLexer):
     """
     For C++ source code with preprocessor directives.
     """
     name = 'C++'
     aliases = ['cpp', 'c++']
     filenames = ['*.cpp', '*.hpp', '*.c++', '*.h++',
                  '*.cc', '*.hh', '*.cxx', '*.hxx',
                  '*.C', '*.H', '*.cp', '*.CPP']
     mimetypes = ['text/x-c++hdr', 'text/x-c++src']
     priority = 0.1

     tokens = {
         'statements': [
 #            (r'(asm|catch|const_cast|delete|dynamic_cast|explicit|'
 #             r'export|friend|mutable|namespace|new|operator|'
 #             r'private|protected|public|reinterpret_cast|'
 #             r'restrict|static_cast|template|this|throw|throws|'
 #             r'typeid|typename|using|virtual)\b', Keyword),
 #            (r'(class)(\s+)', bygroups(Keyword, Text), 'classname'),
 #            inherit,
             (r'(alignas|alignof|asm|carries_dependency|catch|'
              r'char16_t|char32_t|const_cast|constexpr|decltype|'
              r'delete|dynamic_cast|explicit|export|final|friend|'
              r'mutable|namespace|new|noexcept|noreturn|nullptr|'
              r'operator|override|private|protected|public|'
              r'reinterpret_cast|restrict|static_assert|'
              r'static_cast|template|this|thread_local|throw|'
              r'throws|typeid|typename|using|virtual)\b', Keyword),
             (r'(class)(\s+)', bygroups(Keyword, Text), 'classname'),
             inherit,
          ],
         'root': [
             inherit,
             # C++ Microsoft-isms
             (r'__(virtual_inheritance|uuidof|super|single_inheritance|'
              r'multiple_inheritance|interface|event)\b', Keyword.Reserved),
             # Offload C++ extensions, http://offload.codeplay.com/
             (r'(__offload|__blockingoffload|__outer)\b', Keyword.Pseudo),
         ],
         'classname': [
             (r'[a-zA-Z_][a-zA-Z0-9_]*', Name.Class, '#pop'),
             # template specification
             (r'\s*(?=>)', Text, '#pop'),
         ],
     }

     def analyse_text(text):
         return 0.1