SphinxとPandoc

Sphinx

• Python で書かれたドキュメンテーションツール
• reStructturedText でソースコードを作成
• 出力フォーマットがそれなりにある
• toctree
• 拡張が豊富であるだけでなく、自身で作成することも可能
• 導入コストが高いかな

チームとしての導入の壁

環境

Python

ソースがreStructuredText

機能的にはMarkdownよりも優れているが、
みんな書けるわけではない⇒学習コスト

ビルドのタイミング

make html

Pandoc

• Haskell製のドキュメント変換ツール
• 対応フォーマットがたくさん
• オプションもたくさん
• 開発が活発かつ比較的容易
• 基本的には何らかのフォーマットで作ったものを別のフォーマットに変換する
• 導入コストがそんなに高くない
• Pandocは独自の拡張Markdown が便利

Pandoc対応形式

入力形式

• markdown
• Textile
• reStructuredText
• HTML
• LaTex
• MediaWiki markup
• Haddock markup
• OPML
• Emacs Org-mode
• DocBook

出力形式

• プレーンテキスト
• markdown
• reStructuredText
• XHTML
• HTML 5
• LaTeX （beamerスライドショーを含む）
• ConTeXt
• RTF
• OPML
• DocBook
• OpenDocument
• ODT
• Word docx
• GNU Texinfo
• MediaWiki markup
• EPUB (v2またはv3)
• FictionBook2
• Textile
• groff manページ
• Emacs Org-Mode
• AsciiDoc
• InDesign ICML
• HTMLスライドショー：Slidy、Sleous、DZSlides、reveal.js、S5
• PDF出力（LaTeXがインストールされているシステムで使用できます）

Pandocの使い方

準備

Pandocをインストール

macでbrewなら以下が参考になる

Mac に brew で pandoc をインストールする方法

実践

• 別ファイルに出力
  pandoc -o output.hoge input.hoge

• httpを用いてコンテンツの取得
  pandoc -f html -t markdown http://hogehoge.org

• markdownからhtmlに
  pandoc -o output.html input.md

• markdownからシンタックスハイライトされた目次付きhtml出力
  pandoc --toc -s -t html5 -c hoge.css -o output.html input.md

• オリジナルmarkdownに強制改行とグリッドテーブル追加してhtml出力
  pandoc -s -t html5 -o output.html -f markdown_strict+grid_tables+hard_line_breaks input.md

Sphinx or Pandoc

• ドキュメントのバージョン管理も含めてきっちりやるなら Sphinx
  • 但し、reStructuredText・・・
    • Pandoc > reStructuredTextで解決するっちゃ解決する。
  • Python で書かれているため、Python 界隈では活発に Sphinx についての勉強会が開催されている。
• Pandocはお手軽で便利
  • マークアップの主流であるMarkdownで書けるのが利点。
    • 誰でも書ける
  • 入出力の選択肢が幅広いので色々なものに対応できる。

参考

Pandocユーザーズガイド(日本語版)