忙しい人のためのsphinx 入門 demo
DESCRIPTION
Python札幌3.14で発表したときのスライドです。TRANSCRIPT
忙しい人のためのSphinx demo
@ t u t u t e n( m o m o _ * )
あんた誰?
Sphinxって何?
インストール手順
reStructuredTextについて
テーマについて
@tututen (momo_*)
道東、北見で働くITエンジニア
C言語とかさわれます
C++とか基礎すっ飛ばしてBoost入門中
パネポンの対戦者募集中です
あんた誰?
北見の場所
札幌←→北見間 294km(高速道路を使用しない)
Sphinxって何?プレーンテキストのファイルから、各種形式のファイルをエクスポートするプログラム
Sphinxって何?拡張機能で、機能を追加していくことができる
ドキュメントは100%日本語化されている
sphinx-user.jp
強力なコードハイライト
利用実績多数!
国内:http://sphinx-users.jp/example.html
国外:http://sphinx.pocoo.org/examples.html
と、ここまで言いましたが
全部受売だったりします
Slideshareで、sphinxで検索すると...
インストール手順Windows
http://sphinx-users.jp/gettingstarted/install_windows_standalone.html
Mac
$ sudo port install python-sphinx
$ brew install sphinx
Ubuntu
$ sudo aptitude install python-sphinx
インストール後コマンドプロンプト、コンソール画面からsphinx-quickstartを実行する
とりあえずはEnter連打!
次の3つだけは回答する
プロジェクト名
バージョン番号
著者名
reStructuredTextreST(reSturucturedText)
http://sphinx-users.jp/doc10/rest.html
テキストでも見やすい形
見出し
コードブロック
文書内/文書外リンク
表
doctreeなどを作成する
インストール後
こっから先は実演を交えて紹介していきたいと思います。
見出し=、-などでデコレーションしたもの
例:==========大見出し==========
中見出し==========
小見出し----------------
リスト先頭に「-」や「#」、「数字」をつける
例:- リスト1- リスト2
7. 数字リスト1#. 数字リスト2
コードブロック.. code-block:: python print ‘hello world’
のように書く
pygmentsが対応している言語であれば、どんな言語もシンタックスハイライトで表示可能
.. literalinclude :: hello.py
のようにファイルを指定することも可能
表-、+、=、-、|で表現した物を表示する
例:(一番複雑なもの)+-------------------------------------------------+|python 札幌 3.14 発表者 |
+===============+================+|name | contents |+-----------------------+-------------------------+|nakayoshix | reading |+------------------------+------------------------+|giginet | django |+------------------------+------------------------+
内部リンク
内部リンクの定義:.. _sample:
内部リンクの参照::ref:`sample` ←見出しの直前に定義が必要:ref:`ほげほげ<sample>`
外部リンク
外部リンクの定義:
`Yahoo! Japan<http://www.google.co.jp>`_
Yahoo! Japan というように表示される。だけど、飛ぶ先はGoogleに飛びます。
画像貼りたい
.. image :: image/path.png :width: 800px
という感じに書きます。
ここまで出来ればドキュメント作成できますね
しかしデフォルトのテーマですと
ちょっとださい物足りないですよね
でも画面デザインとか
面倒臭い!やりたくない!
そんなあなたに朗報です!
外観の変更
自分でテーマを作成
既存のテーマを組み込む
既存のテーマの探し方
Google 先生に聞く
PyPIで探す
デフォルトを使い倒す
閑話休題
PyPIってどう読むの?
「パイピー」?
「パイパイ」?
イアンさんのツイート
https://twitter.com/#!/ianmlewis/status/111953196544557056
PyPIってどう読むの?
公式的には「パイピーアイ」らしいですが、個人的には、「パイピー」を押し貫こうと思います。(キリッ
話を戻しまして
テーマファイルの探し方
PyPIで”sphinx theme”で検索する
検索結果
どんなテーマがあるの?sphinxjp.themes.bizstyle
sphinxjp.themes.sphinxjp
sphinxjp.themes.trstyle
sphinxjp.themes.solarized
cloud_sptheme
z3c.recipe.sphinxdoc
sphinxjp.themes.htmlslide(プレゼン用テーマ)
sphinxjp.themes.s6 (プレゼン用テーマ)
テーマたくさんあるね!
どれも気に入るものがない?
じゃぁ、作ってPyPIに載せちゃおう!
パッケージの作成・配布の仕方は、エキPyの第7章を参考に!
ご静聴ありがとうございました