================
原稿作成とビルド
================
.. meta::
:keywords: Sphinx,入門,実践入門,reStructuredText,変換,Makefile,Org-mode,Pandoc,原稿,執筆
:description: Sphinxでドキュメントをビルドしてウェブサイトを作成し、EmacsのOrg-modeを変換し、ドキュメントをビルドします。
本章では、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 `__\ というツールを提供しています。本ツールを利用することで、ドキュメントのソースディレクトリを生成し、それにデフォルトの設定ファイル等を追加します。
.. code-block:: bash
sphinx-quickstart
コマンドライン方式：新規プロジェクト作成
----------------------------------------
コマンドラインでSphinxのプロジェクトを作成できる方法を紹介します。
.. code-block:: bash
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ファイルが出力します。
.. code-block:: bash
make html
Sphinx で作成されたウェブサイトを確認
-------------------------------------
何も設定を行っていないウェブサイトです。
ウェブサイトのデザイン変更
==========================
デザインを変更しないとテンションが上がらないため、最近よく見かけるようになった
`Read the
Doc `__\ のデザインを適用します。
conf.py の変更
--------------
.. code:: python
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 つまで
本文
----
- 本文
- 行の途中で改行しない
数式
----
.. math::
E = m c^2
.. math::
y = \sin x
.. math::
f(x) = \sum_{i=0}^n x_i
図
--
図の表示サンプル
.. figure:: ../../_static/sphinx.png
:alt: 画像の挿入
画像の挿入
表
--
============ ==============
Key の見出し Value の見出し
============ ==============
key1 Value1
key2 Value2
============ ==============
ソースコード
------------
ソースコードの表示サンプル
Bash の場合
~~~~~~~~~~~
.. code-block:: bash
echo "Hello Bash!!"
Ruby の場合
~~~~~~~~~~~
.. code:: ruby
puts "Hello World";
Python の場合
~~~~~~~~~~~~~
.. code:: 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 のみの紹介です。
- ソースコード
.. code:: go
main = putStrLn "Hello, World!"
- 実行例
.. code-block:: bash
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に変換
================================================
ファイル名を指定して変換する場合
--------------------------------
.. code-block:: bash
pandoc \
--standalone \
--from org \
--to rst \
--output test.rst \
test.txt
ディレクトリ内のファイルに適用する場合
--------------------------------------
- テキストファイルの拡張子が ".txt" のファイルを順番に処理する
- 処理の内容は、org-mode から rst ファイルに変換すること
.. code-block:: bash
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