SphinxのRead The Docsドキュメントをローカルで作る方法

2023年12月25日

本記事の主旨

ローカルの環境で、SphinxのRead The Docsテーマを使用してWEBでも公開できるHTMLドキュメントを作る方法について記す。

本記事の目的

　本記事の目的を以下に記す。

• Read The Docsテーマを用いたドキュメントを作成する。
• 自分の借りた、もしくは持っているサーバーで公開できるHTMLドキュメントを作る。
  • Read The Docsに登録しなくてもWEBサーバーで公開できるようなドキュメントを作成する。

本記事の背景

Read The Docsドキュメントはきれいな見た目をしている。しかし、なかなかそれをローカルで作成している参考文献を見かけない。また、自分の操作できるWEBサーバーでそのドキュメントを公開する方法も見かけない。

環境構築

Sphinxインストール

1. 以下のコマンドでインストールした。

PS E:\実験\Sphinx> pip install sphinx

2. 以下のコマンドでバージョン確認した。

PS E:\実験\Sphinx> sphinx-quickstart --version
sphinx-quickstart 7.2.6

Read The Docsテーマインストール

以下のコマンドでインストールした。

PS E:\実験\Sphinx> pip install sphinx_rtd_theme

Sphinxプロジェクト作成

1. sphinx-quickstartコマンドでコマンドライン引数の第一引数をテーマ名とした。これでテーマ名をフォルダ名とするフォルダの中にプロジェクトができる。

例：sphinx-quickstart sphinx_rtd_theme

2. プロジェクト作成時は対話形式で設定を入力する。それぞれ以下のように入力した。

• > Separate source and build directories (y/n) [n]: y
• > Project name: test
• > Author name(s): kojichu.com
• > Project release []: 0.01
• > Project language [en]: ja

HTMLドキュメントを開く

sourceフォルダと同じ階層にある、buildフォルダの中にhtmlフォルダがある。その中のindex.htmlを開くと表示される。

階層構造のドキュメントを作成する方法

以下の記事で説明している。

参考サイト

以下のサイトが公式の公認するテーマのギャラリーとサンプルソースである。

公認ギャラリー

公認サンプルコード

広告

Sphinxのインストールやビルドについて書かれた本。初心者向けで基本的なことのみ書かれている。

reStructuredTextの使い方が詳しく書かれているため、reStructuredTextを使用するには一番参考になる本。