Sphinxを利用してGitHub Pages上にドキュメントを公開しよう

# やりたいこと

Pythonのプロジェクトに

1. docstring(google style)形式で記述した内容を
2. Sphinxを利用してhtmlドキュメントを作成して
3. GitHub Pagesを利用して公開する

が目標です。

# 用語説明

## docstringとは

モジュールやクラス、メソッドの直後に記載される`"""`で囲まれた文字列リテラル。[参考](https://en.wikipedia.org/wiki/Docstring)
docstringの書き方はこのページでは紹介しません。

```python
"""The module's docstring"""

class MyClass:
    """The class's docstring"""

    def my_method(self):
        """The method's docstring"""

def my_function():
    """The function's docstring"""
```

## Sphinxとは

Sphinxは知的で美しいドキュメントを簡単に作れるようにするツール。[参考](https://www.sphinx-doc.org/ja/master/)

## Github Pagesとは

Githubが公式に提供する静的なホスティングサービスのこと。[参考](https://docs.github.com/ja/github/working-with-github-pages/about-github-pages)

# 実際にやってみる

早速やってみよう。

## 環境

ubuntu: 20.04.1 LTS
python: 3.8.5
pip: 20.0.2

## プロジェクト構成

### 完成予想図

こんな感じのプロジェクト構成を目指します。
[ここ](https://github.com/HisanoYukito1/sphinx_test)に完成後のサンプルを置いておきます。

```
project/
 |- package1/
 |   |- __init__.py
 |   |- package1.py
 |   |- package2/
 |       |- __init__.py
 |       |- package2.py
 |- docs_src/
 |   |- ...
 |- docs/
 |   |- ...
 |- main.py
 |- README.md
 |- dockerfile/
     |- Dockerfile
```

**package1**
サンプル用モジュールです。

**package2**
サンプル用サブモジュールです。

**docs_src**
documentを作るための作業ディレクトリです。

**docs**
htmlを保存するためのディレクトリです。

**dockerfile**
今回試した環境のDockerファイルが置いてあります。

### 開始時の構成

```
project/
 |- package1/
 |   |- __init__.py
 |   |- package1.py
 |   |- package2/
 |       |- __init__.py
 |       |- package2.py
 |- docs/
 |- main.py
 |- README.md
```

## 手順

[このページ](https://qiita.com/futakuchi0117/items/4d3997c1ca1323259844)を参考にさせていただいました。

### 環境構築

以下のコマンドで`sphinx`をインストールします。
`sphinx_rtd_theme`は見た目をイイ感じにするときに使います。

```bash
$ pip install sphinx sphinx_rtd_theme
```

※[サンプル](https://github.com/HisanoYukito1/sphinx_test)のDockerfileを使う場合には既にインストール済みなので不用。

### 作業ディレクトリ生成

`sphinx-quickstart`を利用して、html作成の作業ディレクトリを生成します。
projectディレクトリにいる状態で以下を実行します。

```bash
> sphinx-quickstart docs_src
```

すると色々聞かれるので回答します。

```bash
> Separate source and build directories (y/n) [n]:
```

ビルドとソースのディレクトリを分けるか聞かれています。
今回は分けたいので、そのままEnterを押下。

```bash
> Project name: test
> Author name(s): Bob
```

プロジェクト名と作者の名前。
ここは省略不可なので適当に入力してください。

```bash
> Project release []:
> Project language [en]:
```

バージョンと言語。
そのままEnterでOKです。

### conf.pyの編集

ここまででやると、`docs_src`ディレクトリ下に`conf.py`ができています。
`conf.py`を開いて、ドキュメント生成のための設定を追記します。

#### pythonプロジェクトへのパスを通す
`conf.py`から見たパスになるので、一つ上のディレクトリを指定します。

```python
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
```

```python
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
```

#### 拡張機能の設定

```python
extensions = [
]
```

```python
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.githubpages'
]
```

**sphinx.ext.autodoc**
docstringを自動で読み込むために必要。

**sphinx.ext.napoleon**
Googleスタイルのdocstringを整形するために必要。

**sphinx.ext.githubpages**
作成するhtmlドキュメントをGitHub Pagesで公開するために必要。

#### テーマ変更

```python
html_theme = 'alabaster'
```

```python
html_theme = 'sphinx_rtd_theme'
```

他にも色々あります。
https://www.sphinx-doc.org/ja/1.4/theming.html

### ドキュメント生成

**rstファイル作成**

`sphinx-apidoc`を使用してhtmlの元となる、rstファイルを作成します。
以下のコマンドを実行すると`docs_src`下にモジュール毎のrstファイルが作成されます。

```bash
$ sphinx-apidoc -f -o ./docs_src .
```

**htmlページ作成**

先ほど作ったrstを使用して、`docs`ディレクトリ下にhtmlファイルを作成します。
***GitHub Pagesでページを公開するためには、docsディレクトリ下にhtmlファイルを作成しなければならない事に注意。***


```bash
$ sphinx-build -b html ./docs_src ./docs
```

**ドキュメント確認**
作成された`index.html`を適当なブラウザで開いてください。
こんな感じに表示されていれば成功です。
![スクリーンショット 2021-02-27 0.43.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/557050/c7d6785f-9e5f-6971-af94-53ef2905cffe.png)

### Githubで公開

ここまでできたら、プロジェクトをgithubへプッシュ。

githubのプロジェクトページへ移動し、`Settings`をクリック。

![スクリーンショット 2021-02-27 0.50.42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/557050/18958acd-b49b-0b88-9f63-b3c49f8f9f88.png)

下にスクロールして、Github Pagesの項目を探します。
見つけたら、Sourceをmain branchの`docs`ディレクトリに変更します。
ここに記載されている、公開したいGitHub Pagesのアドレスはコピーしておきます。

![ pages.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/557050/4bac7fc9-03d3-b67b-e3aa-4acd1695c8ee.png)

最後に、README.mdにGithub Pagesのアドレスを貼り付けて完了です！！
![スクリーンショット 2021-02-27 1.07.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/557050/1c666d55-f64a-944d-0d73-e6c019585265.png)

# まとめ

これでドキュメント自動化への第一歩が踏み出せた。