原稿作成とビルド¶

　本章では、Sphinxの基本的な使い方を学びます。 Sphinxでプロジェクトを開始し、ビルドして成果物(HTML)ができるまでの一連の流れをまとめます。見栄えのよいHTMLが簡単に作成できることをを体験しましょう。

　ドキュメントにおいて、最も大事なのはコンテンツです。読み手にとって必要な情報が、分かりやすく正確に記載されていることが大事です。コンテンツを効率的に作成する作業するために、エディタにもこだわった結果、Emacsを利用するようになりました。そこで出会ったOrg-modeが素晴らしく、もはや、Org-modeがあるから、 Emacsを使用していると言っても過言ではないほどお世話になっています。 Org-modeを利用することで、ドキュメントを構造的に把握し、体系的に編集することができます。

　Pandocを利用し、用意したOrg-modeフォーマットのファイルから rst（reStructuredText）フォーマットへ変換します。そして、Sphinxでビルドし、見栄えのよいウェブサイトを作成します。

Sphnixの概要¶

　Sphinxとはドキュメントを作成するPython製のツールです。何がうれしいのかを、以下にまとめてみます。

知的で美しいドキュメントを簡単に作成できること
- 出力形式: HTML ・ PDF (LaTeX を使用) ・ ePub
- (インデックス等を自動で作成できる)
Python 製ドキュメンテーション作成ツールとして実績があること
- reStructuredText の文書をドキュメンテーションに変換できる
- (Python の公式ドキュメントも採用)
設定やデザインを記事と完全に独立できること
- 記事作成時に細かいデザインを気にしなくてよい
- (レスポンシブに対応したデザインも多数存在)

Sphinxのプロジェクト作成¶

　Sphinxでドキュメントを作成するために、プロジェクトを作成します。プロジェクトを作成する方法には、「対話方式」と「コマンドライン方式」の二つが存在します。

対話方式：新規プロジェクト作成¶

　Sphinxは、sphinx-quickstartというツールを提供しています。本ツールを利用することで、ドキュメントのソースディレクトリを生成し、それにデフォルトの設定ファイル等を追加します。

sphinx-quickstart

コマンドライン方式：新規プロジェクト作成¶

　コマンドラインでSphinxのプロジェクトを作成できる方法を紹介します。

project_name="sphinx-template"
auther="masatotoro"
sphinx-quickstart \
  --quiet \
  --project=${project_name} \
  --author=${auther} \
  --language=ja \
  -v 1.0.0 \
  --ext-todo \
  --no-batchfile

作成された新規プロジェクトの中身確認¶

Spninxのプロジェクトをビルド¶

Sphinx でウェブサイトの作成¶

　Sphinxでプロジェクトを作成するとMakefileも生成されます。以下のコマンドを実行して、SphinxでHTMLファイルが出力します。

make html

Sphinx で作成されたウェブサイトを確認¶

何も設定を行っていないウェブサイトです。

ウェブサイトのデザイン変更¶

　デザインを変更しないとテンションが上がらないため、最近よく見かけるようになった Read the Docのデザインを適用します。

conf.py の変更¶

html_theme = "sphinx_rtd_theme"

Sphinxの課題と対応方針¶

Sphinxはとても簡単にウェブサイトが作成することができます。またデザインに関しても、ライブラリを入れて設定を行うことでいい感じになります。 Sphinxの問題点は、rst(reStructuredText) のフォーマットを覚えなければいけないことです。

Org-modeの概要¶

Org-modeとは、”高速で効率的なプレーンテキストのシステム”です。プレーンテキストで記載すると、様々なプラットフォームでファイルを編集をできるメリットがあります。 Dropbox などで同期すると、その利便性はさらに向上すると思います。

Org-modeはGTD（Getting Things Done）などのタスク管理や、体系的なドキュメント作成と相性がよいです。ここでは、ウェブサイト用のコンテンツを作成する視点で、 Org-modeの便利な機能を厳選してまとめます。紹介する内容はOrg-modeの機能の一部にすぎません。興味のある方は、ぜひ使いこんで理解を深めてください。

Org-mode の公式サイト¶

http://orgmode.org/ja/

Org-mode の嬉しいところ¶

使用して嬉しいと感じる理由は以下の３つです。

テキストデータなので軽量であること
文章の構造を意識して記事作成ができること
作成した記事の活用できる幅が広いこと

サイトの記事を作成する際のフォーマットは Org-mode で統一します。

Org-mode でやりたいこと¶

Emacs の org-mode を用いてファイルを変更
- Goemon によるリアルタイムプレビュ

Org-modeで可能な表現の整理¶

ウェブサイト作成を想定した場合に使用する Org-mode の記法を整理します。複雑なことを行わないことがポイントになります。早速、順番に確認していきましょう。

メタタグ指定¶

SEO 的に、やって置いた方が良さそうなので、メタタグ追記

:keywords: キーワード
:description: 説明文

参考情報¶

http://bacchus.ivory.ne.jp/vodka/doc/sphinx-meta.html

見出し¶

ルール
- 記号: 「*」
- 階層: 3 つまで

見出し階層の２つまでを用いて目次として出力する。そのため見出しの文字列が重複しないようにすること。

箇条書き¶

ルール
- 記号: 「-」
- 階層: 3 つまで

本文¶

本文
- 行の途中で改行しない

数式¶

\[E = m c^2\]

\[y = \sin x\]

\[f(x) = \sum_{i=0}^n x_i\]

図¶

図の表示サンプル

画像の挿入¶

表¶

Key の見出し	Value の見出し
key1	Value1
key2	Value2

ソースコード¶

ソースコードの表示サンプル

Bash の場合¶

echo "Hello Bash!!"

Ruby の場合¶

puts "Hello World";

Python の場合¶

print ("Hello World");

UML¶

ソフトウェアを嗜む場合は、UML が記述できると嬉しいかと思います。

Org-mode でも Sphinx でも plantuml を利用することが可能です。

注釈¶

注釈の表示サンプル

Note

注釈です

Warning

警告です！

Todo

課題です！

Pandocによるフォーマット変換¶

Pandoc とは、以下の特徴をもつツールになります。

Haskell で書かれたライブラリおよびコマンドラインツール
マークアップ形式で書かれた文書を別の形式へ変換することが可能

Sphinx 実践入門では、Pandoc 用いて、Org-mode から reStructuredText に変換することを行います。

これができると、Org-mode で編集したコンテンツを Sphinx でウェブサイトに変換することができます。

公式サイト
- “a universal document converter”

[補足] Haskell とは¶

公式サイト
- Haskell (ハスケル) は非正格な評価を特徴とする純粋関数型プログラミング言語

Haskell の Hello World¶

Haskell は不勉強のため、Hello World のみの紹介です。

ソースコード

main = putStrLn "Hello, World!"

実行例

ghc -o hello hello.hs
./hello

Pandocの対応フォーマット¶

変換元¶

Emacs Org-mode
markdown
Textile (のサブセット、以下同様)
reStructuredText
HTML
LaTeX
MediaWiki markup
Haddock markup
OPML
DocBook

変換後¶

HTML スライドショ: Slidy ・ Slideous ・ DZSlides ・ reveal.js ・ S5
プレーンテキスト
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
PDF 出力（LaTeX がインストールされているシステムで使用できます）

Pandocの変換能力ダイアグラム¶

Pandoc の変換をダイアグラムにした画像があったので紹介します。

Pandocを用いてOrg-modeからreStructuredTextに変換¶

ファイル名を指定して変換する場合¶

pandoc \
 --standalone \
 --from org \
 --to   rst \
 --output test.rst \
 test.txt

ディレクトリ内のファイルに適用する場合¶

テキストファイルの拡張子が “.txt” のファイルを順番に処理する
処理の内容は、org-mode から rst ファイルに変換すること

for file in source/*.txt; do
  # pandoc -f org -t rst $f -o "source/`basename ${file} .txt`.rst";
  pandoc \
    --standalone \
    --from org \
    --to   rst \
    --output "source/`basename $f .txt`.rst" \
    ${file}
done