Sphinx and ME¶

Sphinx と 僕

〜 Sphinxと戯れたいあなたに送る入門編 〜

Who are you?

対象者

目次

• Sphinx概要
• HTMLテーマを変える
• 中身と拡張の話
• ドキュメント作成が捗る
• 参考
• まとめ

Sphinx概要

• Sphinxとは
• はじめてみる
• ReStrucutedText
• いろいろなアウトプット

Sphinxとは

http://sphinx-doc.org/

はじめてみる

$ virtualenv --distribute env
$ source env/bin activate

$ mkdir sample-doc
$ cd sample-doc

$ pip install Sphinx
$ sphinx-quickstart

# 対話形式でSphinxのプロジェクト設定を行う

$ make html

はじめてみる

sample docment

初期構成

./
 ├── Makefile
 ├── _build
 ├── _static
 ├── _templates
 ├── conf.py
 ├── index.rst
 └── make.bat

.. sample documentation master file, created by
   sphinx-quickstart on Tue Sep 10 18:28:57 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sample's documentation!
==================================

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

いろんなアウトプット

pdf, latex, epub, ..etc

$ make latexpdf

HTMLテーマを変えてみる

• 標準テーマ
• CSSを変更する
• 外部テーマ利用
• HTMLテーマの中身

標準テーマ

• agogo
• basic
• default
• haiku
• nature
• pyramid
• scrolls
• sphinxdoc
• traditional

conf.py

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'nature'

build

$ make html

CSSを変える

_stacic/override_nature.css

@import url(https://fonts.googleapis.com/css?family=Ubuntu);
div.body {
    font-family: Ubuntu, Arial, sans-serif;
    background-color: #dcd8d6;
}
div.related {
    background-color: #e46d3d;
}
div.body h1 {
    border-top: 20px solid #dcd8d6;
}
div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
    font-family: Ubuntu, Arial, sans-serif;
    background-color: #c1b3ad;
}

conf.py

def setup(app):
    app.add_stylesheet('override_nature.css')

JSも追加可能

conf.py

def setup(app):
    app.add_javascript('other.js')

外部テーマ利用

save theme files to local

_theme/flask

conf.py

sys.path.append(os.path.abspath('_theme'))
html_theme_path = ['_theme']
html_theme = 'flask'

install

$ pip install sphinxjp.themes.bizstyle

conf.py

extensions += ['sphinxjp.themecore']
html_theme = 'bizstyle'

HTMLテーマの中身

default/
   ├── layout.html
   ├── static
   │   ├── default.css_t
   │   └── sidebar.js_t
   └── theme.conf

defaultテーマのファイルレイアウト

theme.conf

[theme]
inherit = basic          # <= どのテーマを継承するか
stylesheet = default.css # <= どのスタイルシートを利用するか
pygments_style = sphinx  # <= ソースコードハイライトのスタイル

[options]                # <= テーマ固有のオプション
rightsidebar = false
stickysidebar = false
collapsiblesidebar = false
externalrefs = false
.
.

layout.html

{#
    default/layout.html
    ~~~~~~~~~~~~~~~~~~~

    Sphinx layout template for the default theme.

    :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
#}
{%- extends "basic/layout.html" %}

{% if theme_collapsiblesidebar|tobool %}
{% set script_files = script_files + ['_static/sidebar.js'] %}
{% endif %}

テンプレートにはJinja2を採用

layout.html

theme.conf

collapsiblesidebar = true

layout.html

{% if theme_collapsiblesidebar|tobool %} # => True

conf.py

html_theme_options = {
  'collapsiblesidebar': True,
}

利用者が任意に変更できるオプションを追加できる

default.css_t

body {
    font-family: {{ theme_bodyfont }};  <= option
    font-size: 100%;
    background-color: {{ theme_footerbgcolor }}; <= option
    color: #000;
    margin: 0;
    padding: 0;
}

_tを付ける事でHTML同様Jinja2経由で処理される。

中身と拡張の話

• 拡張とは
• ビルドの流れ
• Directive
• Role
• Builder

拡張とは

• Sphinxの機能を拡張する事ができる
• Sphinxに同梱 or 外部ライブラリ
• sphinx.ext〜 , sphinxcontrib〜 とか付いてるヤツ
• https://bitbucket.org/birkenfeld/sphinx-contrib/

sphinx.ext.todo

conf.py

# 拡張を宣言する
extensions += ['sphinx.ext.todo']

# TODOを表示させる(デフォはFalse)
todo_include_todos = True

index.rst

.. todo::

   あとで本気だす！

.. todo::

   俺はあとでやるぞジョジョー!

.. todolist::

todo

todolist

ビルドの流れ

http://sphinx-users.jp/doc11/ext/tutorial.html

• フェーズ1の段階でDocツリーが生成
• DocツリーはNodeという単位で構成
• Docツリーは _build/doctrees以下に保存
• フェーズ3で出力可能なNodeに変換
• フェーズ4でBuilderに併せて出力

Directive

• reSTで特別な意味を持つ文章のブロックを表現

.. ディレクティブ名:: 引数 ...
   :オプション: 値

   ディレクティブのコンテンツ

sphinxjp.themes.revealjs

ブロック内の文章

.. revealjs:: sphinxjp.themes.revealjs
   :data-background: _static/image/background.png

   ブロック内の文章

class revealjs(nodes.General, nodes.Element): pass

class RevealjsDirective(Directive):
    """ Reveal.JS slide entry  """

    node_class = revealjs

    def run(self):
        """ build revealjs node """

        # 省略〜

        node = self.node_class(text, **self.options)
        return [node]

def visit_revealjs(self, node):
    """ build start tag for revealjs """

    # 省略 〜

    self.body.append(self.starttag(node, 'section', **section_attr))

def depart_revealjs(self, node=None):
    """ build end tag for revealjs """
    self.body.append('＜/section＞\n')

def setup(app):
    """Initialize """
    app.info('Initializing RevealJS theme directives')
    app.add_node(revealjs, html=(visit_revealjs, depart_revealjs))

Role

• reSのマークアップの要素で、テキスト中にマーキングを行うことができます。

:ロール名:`コンテンツ`

PEP Role

Pythonのコーディングスタイルは :pep:`8` に従いましょう

Pythonのコーディングスタイルは


 PEP 8

に従いましょう

Roleを使う時の注意

Roleを使う時は両端にスペースを必須

× Pythonのコーディングスタイルは:pep:`8`に従いましょう
○ Pythonのコーディングスタイルは :pep:`8` に従いましょう

Roleも拡張可能

• virtaulenvwrapperの作者
• http://doughellmann.com/2010/05/defining-custom-roles-in-sphinx.html

Builder

• Docツリーを最終的なアウトプットとして吐き出す
• Builder自体でも独自用意する事ができる
• http://www.freia.jp/taka/blog/rst2textile-0.1.0-released/index.html
• https://github.com/nishio/rst2inao

ドキュメント作成が捗る

• 自動ビルド
• APIリファレンスを作る
• DB定義をreST化する
• 良く使う拡張

自動ビルド(watchdog)

• 毎回ビルドするのが面倒
• ファイルを更新したら勝手にビルドしておいて欲しい

watchdog

install

$ pip install watchdog

watchmedo

$ watchmedo shell-command --recursive --patterns="*.rst" --wait --command='make html'

自動ビルド(jenkins)

• pythonアプリのドキュメントを書く事を想定
• docsディレクトリにSphinxドキュメントを用意
• Mecurialでソース管理
• docs用のブランチを切っておく

project
 ├── apps
 ├── docs
 │   ├── Makefile
 │   ├── _build
 │   ├── _static
 │   ├── _templates
 │   ├── conf.py
 │   ├── index.rst
 │   └── make.bat
 ├── manage.py
 ├── polls
 └── requirementxs.tt

リポジトリの設定

• docsブランチを指定

ビルドの設定

• 初回はvirtualenvを作成
• 安全のため make clean

• workspaceにビルドしたドキュメントが生成
• シェルの中にWeb領域にコピーするのを追加しても良い
• pushすれば勝手にビルドしてくれるの嬉しい
• いつでも最新のドキュメントが共有できる

Read the Docs

APIリファレンスを作る

• sphinx.ext.autodocを利用する
• sphinx-apidoc を利用して自動で生成

conf.py

extensions += ['sphinx.ext.autodoc']

autodoc

polls/models.py

from django.db import models

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice = models.CharField(max_length=200)
    votes = models.IntegerField()

autodoc

.. automodule:: polls.models
    :members:
    :undoc-members:
    :show-inheritance:

sphinx-apidoc

• とはいえreSTかくのもダルい
• pythonスクリプトからreSTを自動生成

$ sphinx-apidoc -f -T -o docs/api polls

DB定義をreST化する

• schema2rstを利用する
• DBからテーブル情報を取得してreSTファイル化
• 単なるreSTファイルなのでSphinxでビルド可能
• MySQLのみ対応

$ pip install schema2rst

設定ファイル作る

config.yaml

db: 'polls'
host: '127.0.0.1'
user: 'user'
passwd: 'password'
port: '3306'

コマンド 実行

• SQLAlchemyを利用して接続
• configのDBからテーブル情報取得

$ schema2rst config.yaml > docs/schema.rst

polls_poll
----------

.. list-table::
   :header-rows: 1

   * - Fullname
     - Name
     - Type
     - NOT NULL
     - PKey
     - Default
     - Comment
   * - id
     - id
     - int(11)
     - False

良く使う拡張

• sphinxcontrib-blockdiag

• sphinxcontrib-httpdomain

• sphinxcontrib-issuetracker

参考(Web)

• Sphinx-Users.jp
  • 逆引き辞典
  • ドキュメント資料
  • Sphinxを使用しているサイト
  • Sphinxテンプレート
  • ドキュメント作りたくなってしまう魔法のツール
• Sphinx Advent Calendar 2012
• Sphinx & blockdiag Advent Calendar(全部俺)
• SphinxCon JP 2013 Spring (2013/2/23)
• SphinxCon JP 2012 (2012/9/16)

参考(書籍)

• エキスパートPython
  • 第10章 プロジェクトのドキュメント作成
  • P264 〜
• プロフェッショナルPython
  • Chapter 04 ドキュメント基盤を整える
  • P62 〜
• パーフェクトPython
  • 19章 19-3 ドキュメンテーション(Sphinx)
  • P393 〜

まとめ

• Sphinx概要
• HTMLテーマを変える
• 中身と拡張の話
• ドキュメント作成が捗る
• 参考

今日発表しなかった事

• Sphinxでのドキュメントの書き方(おい)
• ReStructuredTextの詳しい書き方(おい)
• 各種フォーマットでのビルドの仕方(おい)

今日発売! ＼(^o^)／