Sphinx Tutorial at BPStudy#30
Upcoming SlideShare
Loading in...5
×
 

Sphinx Tutorial at BPStudy#30

on

  • 4,171 views

BPStudy #30で説明する内容の抜粋です。ハンズオンで使用しそうなものだけ先にアップします

BPStudy #30で説明する内容の抜粋です。ハンズオンで使用しそうなものだけ先にアップします

Statistics

Views

Total Views
4,171
Slideshare-icon Views on SlideShare
4,160
Embed Views
11

Actions

Likes
5
Downloads
21
Comments
0

1 Embed 11

http://www.slideshare.net 11

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Sphinx Tutorial at BPStudy#30 Sphinx Tutorial at BPStudy#30 Presentation Transcript

    • たのしいドキュメンテーション
      For BPStudy #30, Feb,26th,2010
      日本XPユーザグループ代表(予)
      Python温泉(系), とちぎRuby
      渋川よしき
    • 本日のレシピ
      座学
      Sphinxの歴史
      Sphinxとは何か?
      Wikiとの比較
      Sphinxの使い方
      ハンズオン
      おすすめ書籍紹介ドキュメントを作ってみよう
      座学
      大きなドキュメントを書くための機能
      技術ドキュメントを書くコツ
      Sphinxの内部構造
      1.0以降の展開
    • Sphinxのインストール
      Linux/MacOSXな人
      sudo port install py26-sphinxなど
      Windowsな人
      Pythonをインストール
      easy_installをインストール
      easy_inatall sphinx
      詳しくは: http://blog.shibu.jp/article/32044108.html
    • Sphinxの使い方 -流れ-
      sphinx-quickstart
      django-adminとか、railsコマンドみたいなもの
      質問に答えるとフォルダができる
      ドキュメントを作る
      make XXX
      HTML
      PDFなど
      プロジェクト
      作成
      ドキュメント
      作成
      ビルド
    • Sphinxの使い方を調べるには?
      Sphinx本体の解説
      http://sphinx.shibu.jp/
      reStructuredText
      Sphinx内の入門
      http://sphinx.shibu.jp/rest.html
      reStructured入門
      http://www.planewave.org/translations/rst/quickstart.ja.html
      はやわかりreStructuredText(リファレンス)
      http://www.planewave.org/translations/rst/quickref.html
      Sphinxを使っているサイト
      コード見れます
      Taken by andercismo
      Under CC BY-NC-SA
    • プロジェクトを作ろう
      sphinx-quickstartコマンドで作る
      プロジェクト名、著者名、バージョン以外はEnter連打でOK
      conf.pyを必要に応じて編集すればよい
      既存のスケルトン
      自分のいつも使うスタイルを
      例:@MiCHiLUさんのsphinx-skeleton
      プロジェクト
      作成
      http://bitbucket.org/MiCHiLU/sphinx-skeleton/overview/
    • プレーンテキストのマークアップ
      reStructuredTextを利用
      ソースのままでも可読性が高い
      拡張可能なフォーマット
      注意点
      日本語にはUTF-8で使おう
      すべての異なる要素の間には空行を
      リストの階層が変わる時も
      ドキュメントを作ろう
      ドキュメント
      作成
    • セクションタイトル
      ドキュメント
      作成
      ドキュメントを構成する重要な要素
      #, *, =, -, ^, ~, “などの記号で下だけ、上下を囲う
      自分なりのルールを決めておくと良い
      単体のソース内の登場順でH1, H2, H3..が決まる
      文字長よりも短いと警告が出ます
      ========
      はじめに
      ========
      想定読者
      ========
      新人社会人
      ----------
      はじめに
      想定読者
      新人社会人
    • 親子関係の定義
      ドキュメント
      作成
      Sphinxの一番重要な部分(大規模ドキュメント作成時)
      toctreeディレクティブを使って定義する
      拡張子なしのファイル名を列挙する
      目次がその場で作られる(:maxdepth:でレベルが変わる)
      目次を出したくない場合には、 :hidden:をつけて、:doc:ロールで自分で索引を作る
      .. toctree::
      :maxdepth: 2
      preface
      overview/index
      defensive/index
      • はじめに
      • 本書の考えるゴール
      • 本書を作るにあたって
      • 本書で説明していくこと
      • つまみぐい勉強法
      • 勉強はつまみぐいから
      • 大切なことは、継続
      • 自分に合うものを選ぼう
      • 終着点は自分で決めよう
    • 親子関係の定義
      セクションタイトルを子供の文書から引っ張ってきて目次を作る
      toctree自体は1文書に何個も書ける
      toctree表示位置に、子供の文書のセクション構造が挿入される
      ドキュメント
      作成
      toctreeを制するモノがSphinxを制す
    • 箇条書き
      ドキュメント
      作成
      * を前に付けると、バレットリスト
      #, 数値 + ピリオドで、ナンバー付きリスト
      複数階層もできます
      ただし階層が変わる前後は空行を入れること
      1.トヨタ
      * プリウス
      * クラウンハイブリッド
      2. ホンダ
      * シビックハイブリッド
      * CR-Z
      トヨタ
      • プリウス
      • クラウンハイブリッド
      ホンダ
      • シビックハイブリッド
      • CR-Z
    • フィールドリスト
      ドキュメント
      作成
      :項目名: 値
      著者名、出版日などの情報を列挙したいけど、表にするまでもない時に使えます
      :書名: スクラム
      :訳者: スクラムエヴァンジ..
      :出版社: ピアソン
      :発行日: 2003/09/20
      :本体価格: 2000円
      :ISBN: 9784894715899
      書名:スクラム
      訳者:スクラムエヴァンジ..
      出版社:ピアソン
      発行日: 2003/09/20
      本体価格: 2000円
      ISBN: 9784894715899
    • 画像
      ドキュメント
      作成
      .. image:: ディレクティブで画像を挿入できます
      ::の後ろにファイル名を書きます
      ファイル名は相対パスもしくは、ドキュメントのルートからの絶対パスで指定します
      .. image:: image/tornado.png
    • 外部リンク
      ドキュメント
      作成
      `リンクテキスト <http://ターゲットURL>`_
      最後のアンダースコアを忘れないように
      日本語の文書の中に挿入する場合は、前後にスペース(もしくは¥ + スペース)を入れる
      URLをそのまま入れる
      リンク張ってくれます
      分からないことがあったら `ぐぐって <http://www.google.com>`_ ください
      参考: http://sphinx.shibu.jp
      わからないことがあったらぐぐってください
      参考: http://sphinx.shibu.jp
    • 表(1)
      ドキュメント
      作成
      書き方が4通りあります
      一番複雑な方法
      縦、横のセルの結合ができます
      文字数が変わると編集が面倒
      +-------------+----------------------+---------+---------+------+
      | Feature List | Python2 | Python3 | Ruby |+=============+======================+=========+=========+======+
      | Push API | following_function | O | O | |
      + +----------------------+---------+---------+------+
      | | following | O | O | O |+-------------+----------------------+---------+---------+------+
      | Pull API | Queue | O | O | _ |+-------------+----------------------+---------+---------+------+
    • 表(2)
      ややシンプルな方法
      縦のセルの結合はできません
      文字数が変わると編集が面倒
      list-tableディレクティブ
      かんたんだけど、複雑な制御はできない
      ドキュメント
      作成
      ======= ==== ==============
      入力 出力
      ------------ --------------
      種類 引数 索引
      ======= ==== ==============
      single: A; B A -> B
      single: A A
      pair: A; B A -> B, B -> A
      ======= ==== ==============
      .. list-table::仕様
      :widths: 15 10 10
      :header-rows: 1
      * -主要諸元
      -MXB
      - MX
      * -車両重量
      - 1260
      - 1270
    • 表(3)
      csv-tableディレクティブ
      かんたんだけど、複雑な制御はできない
      ドキュメント
      作成
      .. csv-table:: 郵便番号
      :header: “番号”,“住所”
      :width: 15, 20
      “321-0911”,”宇都宮市問屋町
      “321-0912”,”宇都宮市石井町”
      “321-0923”,”宇都宮氏下栗町”
    • ノート、引用、コードサンプル
      ドキュメント
      作成
      ブロックを挿入するために各種ディレクティブ、::記号を使う
      インデントが終わるまで、ブロックとして扱われる
      ブロック
      .. note::, .. tips::, .. warning::, ::記号など
      コードサンプル
      .. code-block:: ディレクティブを使う
      .. note::
      バージョンにより異なります
      .. code-block:: python
      @auto_twitter("function")
      def sample_function():
      print “do action”
      バージョンにより異なります
      @auto_twitter("function")
      defsample_function():
      print ”do action"
    • ビルド
      コンソールからmake htmlとタイプ
      _build/htmlフォルダ以下に出力されます
      ビルド
    • 本日のレシピ
      座学
      Sphinxの歴史
      Sphinxとは何か?
      Wikiとの比較
      Sphinxの使い方
      ハンズオン
      おすすめ書籍紹介ドキュメントを作ってみよう
      座学
      大きなドキュメントを書くための機能
      技術ドキュメントを書くコツ
      Sphinxの内部構造
      1.0以降の展開
    • ハンズオン(30分)おすすめ書籍紹介ドキュメントを作ってみよう
      二人一組になってください
      Sphinxインストールが完了していない人は完了している人とペアを作ってください
      効率を重視する場ではないのでエディタ論争は禁止
      説明した機能をどんどん使って見ましょう
      練習のために1冊1ファイルで。目標は2冊。
      分からないことがあれば聞いてください