======================
Sphinx実践入門について
======================

.. meta::

   :keywords: Sphinx,入門,実践入門,概要,チュートリアル,tutorial
   :description: Sphinxを活用し、ドキュメントを作成するための概要をまとめます。

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

Sphinx実践入門の目的
====================

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

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

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

Sphinx実践入門の構成図
======================

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

.. figure:: ../../_static/system-constitution.png
   :alt: Sphinx実践入門のシステム構成図

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

Sphinx実践入門の環境構築
========================

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

.. code-block:: bash

   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実践入門」は以下の環境で動作確認を実施しています。

.. table:: 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
   ================ ============

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

.. code-block:: bash

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

Sphinx実践入門の説明の流れ
==========================

#. Sphinx実践入門について
#. 原稿作成とビルド
#. Git管理とGitHub公開
#. 継続的ドキュメンテーション
#. 執筆活動を効率化するノウハウ

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

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

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

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