Sphinx実践入門について

　Sphinx実践入門は、ドキュメントを作成＆共有する方法を解説します。具体的には、プレーンテキストで作成したファイルをドキュメンテーションツールである sphinx で静的ファイルに出力し、ウェブ(GitHub)上に公開することをゴールとします。

Sphinx実践入門の目的

　ソフトウェア開発において、なぜ「ドキュメント」が求められるのでしょうか？設計時にドキュメントを作成し共有しなければ、開発したシステムが属人化 (特定の人しか管理できない状態)になります。したがって、ソフトウェア開発の現場では、設計ドキュメントを作成しながら開発を進めています。しかし、設計ドキュメントの編集・共有にはコストがかかることが課題なっています。

　チーム開発では、Redmine、Confluenceなどツールが持つWiki機能を利用し、設計ドキュメントをまとめることが一般的です。この場合、ドキュメントの編集するためWikiにアクセスし、ツールに依存する記法で編集することを強いられ、編集にコストがかかります。また、複数人でWiki機能を活用してドキュメントをまとめて情報が増えた結果、情報が散在し有効に活用できない問題に遭遇します。その結果、情報をまとめた当事者に、情報の置き場所の問い合わせする事象が発生し、共有にコストがかかります。

　Sphinx実践入門では、ドキュメントを一元管理し体系的にまとめる方法を提案し、チームで協力してドキュメント継続的にメンテナンスする仕組みを構築します。その結果、前述した課題を解決することを目指します。そのために、様々なツールを駆使し、ドキュメントのメンテナンスコストを下げることに取り組んでいます。そして、ソフトウェアエンジニアが、少しでもコーディングに注力できるようになればと願っています。

Sphinx実践入門の構成図

　開発マシンにおいて、 Emacsでドキュメントを編集し Sphinx でビルドすることでHTMLを生成します。成果物であるHTMLを ghp-import を利用し、GitHubのリポジトリにpushします。そして、GitHub Pagesの機能を利用し、ウェブサイトとして公開することを実現します。

Sphinx実践入門のシステム構成図

Sphinx実践入門のシステム構成図

Sphinx実践入門の環境構築

　以下のように pip3 コマンドを利用し、必要なアプリケーションをインストールします。

sudo -H pip3 install sphinx
sudo -H pip3 install sphinx_rtd_theme
sudo -H pip3 install ghp-import
sudo -H pip3 install sphinx-sitemap

対象読者と動作確認環境

対象読者

　本資料の目的は、コンテンツの質向上に専念できる「ウェブサイト構築術」を共有することです。対象読者は、 複数のツールを使いこなし、ウェブサイトの更新を自動化することに興味がある方に設定します。

Note

Emacs をエディタとして使っており、 様々なツールを活用することが好きな方が楽しめると内容になっています。 利用するツールは、Sphinx ・ Pandoc ・ Goemon ・ Jenkins を想定しています。

動作確認環境

　「Sphinx実践入門」は以下の環境で動作確認を実施しています。

Sphinx実践入門の動作確認環境

項目

バージョン

OS

Ubuntu 18.10

pandoc

2.6

GNU Make

4.2.1

GNU sed

4.5

Sphinx

1.8.5

sphinx-rtd-theme

0.4.3

　動作確認を実施する際に利用したコマンドは以下になります。

cat /etc/lsb-release
pandoc --version
make --version
sed --version
pip3 show sphinx
pip3 show sphinx_rtd_theme

Sphinx実践入門の説明の流れ

  1. Sphinx実践入門について

  2. 原稿作成とビルド

  3. Git管理とGitHub公開

  4. 継続的ドキュメンテーション

  5. 執筆活動を効率化するノウハウ

　「Sphinx 実践入門」では、ウェブサイトで一番重要なコンテンツをプレーンテキストで作成することを推奨します。執筆の効率を高めるために、Emacs の Org-mode 記法を採用しました。

　Sphinxでウェブサイトをビルドする方法からを学び、 Pandocを用いてOrg-modeで記載されたプレーンテキストを Sphinxで扱うRSTの記法に変換することに挑戦します。

(Pandoc が対応しているので、markdown でも作成することが可能です)

最後は、Git でドキュメントを管理し、Jenkins を用いてビルドとデプロイの自動化を行うことで継続的なウェブサイト更新ができることを実現します。