読者です 読者をやめる 読者になる 読者になる

secretbase.log

コードはすべてNYSLです

SphinxConJP 2012 (世界ではじめてのSphinxカンファレンス) 参加レポート

SphinxConJP 2012 が本日開催され、計7件のセッションがありました。それぞれスライド内容をレポートとしてまとめました。

Sphinx ではじめるドキュメント生活 2012 @ 15:15-15:40

  • Sphinxについて
    • テキストから各種フォーマットへの変換 (HTML, PDF)
    • Welcome to PEP翻訳 — PEP翻訳 v3642 documentation
    • シンプルなマークアップ (reST) Wiki記法みたいなもの
    • 目次ベースなので文章が書きやすい
    • Sphinxのよいところ
      • ソースがテキスト形式 なので
      • schema2rst (DB定義抽出)
    • いまいちなところ
      • 変換する必要がある(ビルド) Jenkinsなどで自動化はできる
      • reSTは文書レイアウトを表現できない
      • 画像や図などは別途作る必要がある
    • 主な用途
      • 開発ドキュメント、Webサイト、出版
  • Sphinxの現在
    • Wordとの比較
      • 文章構成、複数人での管理はSphinxが向いている
    • Excelとの比較
      • 文章構成、編集、印刷イメージとの一致は、Sphinxが向いている
    • 他のツールとの比較
    • Sphinxテーマの増加
      • スライド系 s6 htmlslide impressjs
      • themecore solarized
  • Sphinxの未来
    • PDFのパッチ取り込み、変換の自動化、PDFテーマ
    • テーマや拡張を増やす、Webエディタ、利用事例
  • Sphinxコミュニティの紹介
  • まとめ
    • #sphinxjp で質問したら誰か共有。面白いネタを提供してください

Sphinx拡張 探訪 @ 15:40-16:05

Sphinx拡張 探訪 — SphinxCon 2012 documentation

    • テーマ
      • 7種類が標準。拡張として sphinxjp.themecore
      • sphinxjp.themes.htmlslide
      • sphinxjp.themes.solarized
      • cloud_sptheme (Beautiful soap のサイト)
    • グラフなど描画系
      • blockdiag,, gnuplot, graphbiz, googlechart, nicovideo, ...
      • sphinxcontrib-aafig
      • sphinxjp.shibukawa カレンダー描画
    • excelなどの変換系
      • wiki2sphinx odt2sphinx など
      • sphinxcontrib-exceltable Excel ファイル指定できる
      • sphinx-git
    • Django/Zopeなどとの連携
      • 試してません>
    • その他
      • sphinxcontrib-osaka 大阪弁になるフィルタ
      • sphinxcontrib-issuetracker BTSのチケットのURL生成
      • sphinxfeed RSSフィールドを生成してくれる
      • sphinxcontrib.spelling
      • sphinx-gettext-helper gettextを便利に
      • Sphinxは豊富な拡張も魅力

Sphinx HTML theme 事始め @ 16:45-17:10

  • HTMLテーマとは何か
    • HTMLテンプレートとCSSの集まり
    • conf.py html_theme
  • 組み込みHTMLテーマの簡単なカスタマイズ
    • 背景色だけ変更したい html_theme_options (辞書型のパラメータ)
    • テーマごとにoptionがある
    • テーマと設定可能なoption
    • サイドバーを隠したい ( "nosidebar": True )
    • default のテーマの option
  • テーマをつくる
    • theme.conf
      • [theme] セクション
        • inherit 継承
        • stylesheet
  • まとめ

Sphinxを使って本を書こう @ 17:10-17:35


  • Pythonプロフェッショナルプログラミングを Sphinxで執筆
  • Sphinxで記述され出版されたもの

エキスパートPythonプログラミング

エキスパートPythonプログラミング


Pythonプロフェッショナルプログラミング

Pythonプロフェッショナルプログラミング

    • buildout を使って環境構築 (sphinx+extensions, fontの同梱)
    • hg clone ; python bootstrap.py
    • 執筆 reST 者にレビューは HTML 社外レビュー PDF
      • 目的別に異なるフォーマットで閲覧
    • 秀和システムビルダーをつくった(丸2日以上)
      • make syuwa
    • まとめ
      • うまくいかなかったこと
        • 提出原稿の自動生成は明確な仕様が必要。戻り原稿の受け取り方も考えておこう
      • うまくいったこと
        • BeProud はドキュメントは全部 reST で書いている
        • 環境用意は自動化しておく

Sphinxの平凡な使い方 ~業務での利用事例~ @ 17:45-18:00

  • 事例その1 スマートなファイル管理
    • サーバ・ディレクトリの使用ルールがないので散乱する
    • ディレクトリ構成によるファイル管理→無理があるのでは?
    • 最強のファイル管理
      • Trac/Redmine等のプロジェクトツールつかおう→付属のWiki
      • mercurial等のバージョン管理ツールを使ったファイル管理
      • Sphinx→ドキュメントやファイルをまとめることはできる
      • :download: ロールを使うと説明付きでファイルを添付することができる
  • 事例その2 簡単にWebサイトをつくりたい
    • 自社でSphinx紹介→メールマガジンでSphinx紹介
    • 社内でSphinxハンズオン開催! > 一人参加..
    • 社内の待機者向けの”待機者ハッカソン”を開催
    • 日報サイト
      • 特的の場所に 日報.rst

社内でのSphinx、reSTの広め方 @ 18:00-18:15

  • How to spread reST and Sphinx
    • MS-Word 使いたくない、らくしたい、reSTで書きたい
    • 1st step 議事録を書く→メール→なんとなく記法に慣れる
      • 心の中にフォーマッターができてくる
    • 2nd step Plone*1 + ReST
      • 議事録を書く、週報を書く(→相互に書き込み)
    • PloneSphinxより検索が賢い。全文検索
      • 普段からreSTを使うようになる , 楽しく書く, 他の人を真似する
    • 3rd step Sphinx
      • チームで資料(要件定義)を書く / 書くことに集中 / 設定したい人は使えるようにする
      • チームでドキュメント
        • Sphinxのファイル構成を全部作る
        • タイトルと担当者をすべて入れる
        • 目次だけできている状態
    • まとめ
      • みんなでドキュメントができた!
      • make html で Warning が消せない問題→たいていは下線が短い、改行がないとか→ひとりで面倒をみた
      • 徐々にひろめる、書くことに集中してもらう、最後は自分で面倒をみる

Sphinxにおけるdocutilsの役割 @ Keita Uchiyama 18:15-18:30

  • DocutilsでHTMLを生成してみよう
    • Sphinx インストールで、 docutils も入る
    • rst2html.py foo.rst > foo.html

さいごに

Sphinx最近 触り始め、先月から社内の技術資料を書き始めリリースしました。SphinxはテキストなのでUNIX文化と親和性がよいし、拡張が豊富なのが魅力的です。
弱いところはWYSIWYGな環境での作成と、図の作成貼り付けあたりだと思います。方向性としては blockdiag や plantUMLといったテキストで図を書くというアプローチもすすんでいます。
今回の SphinxCon は、概要、拡張、テンプレート、導入事例、内部仕様といった多岐に渡るテーマでとてもためになりました。
セカコミ(id:tk0miya) さん、スピーカーの皆様、有難うございました。

*1:Python based CMS