【ナレッジ共有】 sphinx-rtd-themeでいい感じのWebページを作成してみよう！！

いつも記事を読んでいただきありがとうございます！
モブエンジニア（[@mob-engineer](https://qiita.com/mob_engineer))です！

今回はPython製のドキュメント生成ツール**Sphinx**でいい感じのWebページを生成するためのナレッジを共有したいと思います👍

# 目次
| 項番 | タイトル |
|:----:|:-------------|
| 1 | **本記事を役立ててもらいたい方** |
| 2 | **記事内で取り上げること・取り上げないこと** |
| 3 | **SphinxでWebページを作成してみる！** |
| 4 | **テーマをsphinx-rtd-themeに変えてみたが......** |
| 5 | **右余白をいい感じで使えるようにする** |
| 6 | **まとめ** |
| 7 | **参考サイト** |

## 本記事を役立ててもらいたい方
- SphinxでWebページを作成している方
- sphinx-rtd-themeを利用している方

## **記事内で取り上げること・取り上げないこと**
### 記事内で取り上げること
- Sphinx、sphinx-rtd-themeのインストール方法
- sphinx-rtd-themeの右余白利用方法
- よく使うRSTファイル記載ルール紹介

### 記事内で取り上げないこと
- Sphinx運用のベストプラクティス
- CI/CDを含めたSphixn環境
- その他（カスタムCSSを用いた柔軟なデザイン変更など）

## **SphinxでWebページを作成してみる！**
Sphinxを用いてWebページの作成を行っていきます。

### 作業環境へSphinxをインストール

:::note warn
あらかじめ、作業環境で「Python」および「pip」を利用可能にしておいてください。
:::

```Linux:作業環境
$ pip install sphinx
```

- Sphinxインストール後バージョン確認

```Linux:作業環境
$ sphinx-build --version
>sphinx-build <バージョン番号>
```

- sphinx-rtd-themeインストール
- 
```Linux:作業環境
$ pip install sphinx-rtd-theme
```

### Sphinxプロジェクト作成

- プロジェクト作成
- 
```Linux:作業環境
$ sphinx-quickstart docs
```

- 実行後、応答文が表示されるため以下のとおり入力

```Linux:作業環境
Welcome to the Sphinx 7.4.7 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: docs

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
**> Separate source and build directories (y/n) [n]: y 　※yを入力（sourceとbuildファイル分割）

The project name will occur in several places in the built documentation.
> Project name: test-project　※プロジェクト名を入力
> Author name(s): test-project　※作者名を入力
> Project release []: 1.0.0　※リリース番号を入力

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ja　※言語を入力

Creating file /home/ec2-user/sphinx-test/docs/source/conf.py.
Creating file /home/ec2-user/sphinx-test/docs/source/index.rst.
Creating file /home/ec2-user/sphinx-test/docs/Makefile.
Creating file /home/ec2-user/sphinx-test/docs/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /home/ec2-user/sphinx-test/docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
```

:::note info
上記情報は、プロジェクト作成後生成されるConfigファイル（conf.py）で修正可能です。
:::

### 現在のディレクトリ構成
![スクリーンショット 2024-10-21 213320.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3846878/7c53e8ad-3b18-9839-ff2c-4c4564dd9e7f.png)

:::note info
index.rstがトップページ用のソースコードとなります
:::

### index.rstを書き換えよう
以下のとおりindex.rstファイルを書き換えました。
![スクリーンショット 2024-10-21 215038.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3846878/ab2996e7-3b25-137f-8ef9-f92595c57792.png)



:::note info
RSTファイルの記載方法は以下を参照してください
https://docutils.sourceforge.io/docs/ref/rst/directives.html#top
:::

- Sphinx-build実行

```Linux:作業環境
$ sphinx-build -M html docs/source/ docs/build/
```

buildディレクトリ配下にHTMLファイルが生成されます。
build > html > index.htmlをWebブラウザ上で開いてください。

:::note info
VSCodeの場合「Live Server」を利用すれば、「index.html→右クリック→Open With Live Server」をクリックすることでWebブラウザ上に表示できます。
:::

- ブラウザ上での表示イメージ
![スクリーンショット 2024-10-21 215122.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3846878/38e90bb8-e80c-6f74-617f-8a9148bcfc39.png)

### sphinx-rtd-themeに変更する

- conf.py内の以下内容の次のように書き換える

```Python:conf.py
import sphinx_rtd_theme
extensions = ['sphinx-rtd-theme']
html_theme = 'sphinx-rtd-theme'
```

- Sphinx-build実行

```Linux:作業環境
$ sphinx-build -M html docs/source/ docs/build/
```

## **テーマをsphinx-rtd-themeに変えてみたが......**
![スクリーンショット 2024-10-21 215856.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3846878/0c411a5f-420c-cc1f-1547-a77e8879c62f.png)

右側余白も利用したいが、グレーアウトしている......
カスタムCSSの機能を利用していい感じに右余白を利用できるようにしよう

## **右余白をいい感じで使えるようにする** 

- source > _staticディレクトリ配下に、以下custom.cssファイルを作成

```css:ustom.css
.wy-nav-content {
    max-width: 1600px;
}
```

- conf.pyに以下設定を追加

```Python:conf.py
html_css_files = [
    'custom.css',
]
```

- Sphinx-build実行

```Linux:作業環境
$ sphinx-build -M html docs/source/ docs/build/
```

- ブラウザ画面
![スクリーンショット 2024-10-21 220736.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3846878/f0aad51e-9df6-e1ce-57cc-70195a1f08a5.png)

いい感じで右余白も利用できるようになった👍

##  **まとめ**
今回はSphinxに関するナレッジを記事にしました。
ハンズオン系の記事執筆は初めてだったため、慣れないところもありましたが、とりあえずまとめられてよかったと思います。個人的にSphinxは「お手軽Webサイト」を作成するという視点では、（現状）最強のツールだと考えています。引き続き、Sphinx関連のハンズオン記事も執筆したいと思います。

##  **参考サイト**
[Sphinx の sphinx_rtd_theme をカスタマイズする](https://kuttsun.blogspot.com/2016/11/sphinx-sphinxrtdtheme.html)
[reST を書かずに autodoc だけで Sphinx する](https://qiita.com/satamame/items/65abd04e74b341ed1e80)
[Sphinx公式ドキュメント](https://www.sphinx-doc.org/en/master/index.html)

:::note info
最後まで記事を読んでいただきありがとうございます。
読んでみて、「良かった」とおもったらハートボタンとストックを行っていただければ、作者が喜びます！
:::