2024年6月: Python製静的サイトジェネレーターSphinxでWebサイトを構築して公開(takanory)¶
鈴木たかのり（@takanory)です。 今月の「Python Monthly Topics」では、Python製の静的サイトジェネレーターSphinxを使用してWebサイトを構築し、テーマを適用、外部へ公開する流れについて紹介します。 後半ではSphinxの便利な拡張機能を紹介し、Webサイトをより便利にしていきます。
Markdownでドキュメントを書くだけで、きれいなWebサイトが簡単に公開できるので、ライブラリのドキュメントなどでもよく使われています。
Sphinxとは¶
SphinxはPython製の静的サイトジェネレーターです。 静的サイトジェネレーターとは、Markdown等の軽量マークアップのテキストファイルから、静的なWebサイトを生成するアプリケーションのことを言います。 Python製の静的サイトジェネレーターにはSphinxを含め以下のツールなどがあります。
Sphinx: https://www.sphinx-doc.org/
MkDocs: https://www.mkdocs.org/
Lector: https://www.getlektor.com/
Pelican: https://docs.getpelican.com/
他のプログラミング言語ではGo製のHugoやRuby製のJekyllなどがよく知られていると思います。
Sphinxの特徴¶
Sphinxは静的なWebサイト生成だけでなく、ドキュメントを作成することも目的としています。 そのため、Sphinxでは1つのテキストファイルからHTMLだけでなく、PDF（LaTeX経由で作成）やePubなどの文書、書籍向けのフォーマットも生成できます。
また、さまざまな拡張機能が利用できます。 本記事ではSphinxのおすすめの拡張機能についても紹介します。
Sphinxを使用しているサイト、書籍¶
Sphinxを使用しているサイトをいくつか紹介します。 まず、Pythonの公式ドキュメントはSphinxで記述されています。 元となるファイルはGitHubのCPythonリポジトリの中にあります。 なお、公式ドキュメントの翻訳はTransifexという別サービスで行っています。興味のある方はPython Monthly Topicsの過去記事を参照してください。
Python公式ドキュメント: https://docs.python.org/ja/3/
Sphinxは多くのPython公式のドキュメントや、各種Python製ライブラリの公式ドキュメントでも採用されています。以下にいくつか例をあげます。
Python Enhancement Proposals (PEPs): Pythonの拡張提案(PEP)
Python Developer's Guide: Python開発者ガイド
pip: Pythonのパッケージインストーラー
Flake8: Pythonコードのリンター
Requests: HTTPクライアント
Pandas: データ分析ライブラリ
また、前述のようにSphinxは文書、書籍向けのフォーマットも生成できるため、書籍の執筆でも使われています。以下はSphinxで執筆された書籍の例です。 ちなみに、Python Monthly Topicsの下書きもSphinxで執筆しています。
Sphinxの特徴や事例を把握したので、さっそくインストールして使ってみましょう。
Sphinxをインストールして手元で確認¶
まずはSphinxをインストールして手元の環境でWebサイトを確認するところまでの手順を紹介します。
GitHubリポジトリの準備、Sphinxのインストール¶
GitHubで空のリポジトリを作成してからPCにcloneします。 あとでこのリポジトリを使用して、Sphinxのドキュメントを外部サイトに公開します。 以下のサンプルのリポジトリにはこの記事で設定した内容、ドキュメントが入っています。差分を確認するとどのような変更が入ったかわかりやすいと思います。 実際に手元で実験する場合は自分で空のGitHubリポジトリを作成してください。
サンプルのGitHubリポジトリ: https://github.com/takanory/gihyojp-sphinx-sample
% git clone https://github.com/takanory/gihyojp-sphinx-sample
% cd gihyojp-sphinx-sample
次にvenvモジュールを使用して仮想環境を作成し、Sphinxをインストールします。
% python3.12 -m venv env
% . env/bin/activate
(env) % pip install sphinx
Sphinxをインストールすると sphinx-quickstart コマンドが使えるようになるので、コマンドを実行して初期ファイルを作成します。
プロジェクト名、著者などを指定すると初期ファイルが作成されます。
sphinx-quickstart コマンドを実行¶(env) % sphinx-quickstart
> Separate source and build directories (y/n) [n]: y
(省略)
> Project name: Gihyojp Sphinx Sample
> Author name(s): takanory
> Project release []:
(省略)
> Project language [en]: ja
% ls # ファイルを確認
LICENSE README.md env source
Makefile build make.bat
ここでmake htmlコマンドを実行するとHTMLファイルがbuild/html/フォルダー以下に生成されます。
index.htmlファイルをWebブラウザで開くと、結果が確認できます。
make html コマンドを実行してHTMLをビルド¶(env) % make html
(env) % open build/html/index.html
ビルドした結果が確認できた¶
この状態で初期ファイル群をコミットしてプッシュします。 以降、このように変更するためにコミット、プッシュしてGitHub上で差分がわかるようになっています。 ぜひ参考にしてください。
(env) % pip freeze > requirements.txt
(env) % git add .
(env) % git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: Makefile
new file: make.bat
new file: requirements.txt
new file: source/conf.py
new file: source/index.rst
(env) % git commit -m "GitHubリポジトリの準備、Sphinxのインストール"
(env) % git push
差分は以下で確認できます。
ドキュメントを編集、設定をカスタマイズ¶
次にドキュメントを少し書いて、Sphinxの設定も少しカスタマイズします。 まずはドキュメントファイルの「source/index.rst」を書き換えます。 SphinxではデフォルトではreStructuredTextという軽量マークアップ言語で記述します。 ここでは、以下のようにドキュメント全体を書き換えます。
gihyo.jp記事のSphinxサンプル
============================
このドキュメントは、gihyo.jpのPython Monthly Topics(https://gihyo.jp/list/group/Python-Monthly-Topics)でのSphinx記事のサンプルドキュメントです。
* 箇条書き
* 箇条書き
.. code-block:: python
for i in range(100):
print(i)
なお、本記事ではreStructuredText記法について解説はしません。 興味がある方は以下のドキュメントを参照してください。
続いて設定ファイルであるsource/conf.pyを編集します。
まずはテーマを変更します。Sphinxには複数のテーマが組み込まれており、デフォルトではalabasterテーマが指定してあります。
conf.pyのhtml_theme変数の値を変更してここではbizstyleを指定します。
なお、組み込みテーマの一覧はHTML Themingのページで確認できます。
html_theme = 'bizstyle'
また、ドキュメントにロゴ画像を指定します。 Python Monthly Topicsのロゴ画像を使用します。 ダウンロードした画像をsoruce/_static/logo.pngに配置し、conf.pyに以下の記述を追加します。
html_logo = "_static/logo.png"
ここで再度make htmlコマンドを実行してindex.htmlを表示すると、ドキュメントの内容、HTMLテーマが変更、ロゴ画像が追加されていることが確認できます。
ドキュメント、テーマ変更、ロゴを追加¶
Markdownでドキュメントを書く¶
GitHub、QiitaなどMarkdownで記述できるサービスは多いため、Markdown記法に慣れている人も多いと思います。 SphinxではMyST Parserという拡張機能を導入することにより、Markdownを扱えるようになります。 MySTはMarkedly Structured Textの略で、Markdownを拡張してreStructuredTextと同じような機能を提供しています。MySTの拡張記法については以下の公式サイトを参照してください。
MyST Parser: https://myst-parser.readthedocs.io/
まず。MyST Parserをインストールします。 requirements.txtファイルも更新しておきます。
(env) % pip install myst-parser
(env) % pip freeze > requirements.txt
次にsource/conf.pyにMyST Parserを使用するための設定を追加します。
extensions変数のリストに追加するのみです。
extensions = ["myst_parser"]
これで拡張子が.mdのファイルの場合は、MyST Parserが処理するようになります。 source/index.rstを削除してsource/index.mdを追加します。
# gihyo.jp記事のSphinxサンプル
このドキュメントは、gihyo.jpの[Python Monthly Topis](https://gihyo.jp/list/group/Python-Monthly-Topics)でのSphinx記事のサンプルドキュメントです。
Markdownで書いてます。
* 箇条書き
* 箇条書き
```python
for i in range(100):
print(i)
```
make htmlを実行し、Markdownのドキュメントからビルドできていることを確認します。
Markdownからドキュメントをビルド¶
サードパーティーのテーマを利用¶
Sphinxのテーマには組み込みだけでなく、サードパーティーのテーマがあります。 サードパーティーのテーマもインストールして使用ができます。 Sphinx Themes Galleryにはさまざまなテーマがあるので、好みのテーマを探してみてください。
ここでは最近筆者が気に入っているFuroというテーマを使用します。 他にRead the DocsやSphinx Book Themeも使われているサイトが多く、おすすめです。
Furoをインストールし、requirements.txtを更新します。
(env) % pip install furo
(env) % pip freeze > requirements.txt
次にsource/conf.pyでテーマをFuro変更します。
また、html_theme_options変数にGitHubのリポジトリ情報を設定すると、ドキュメントから直接GitHub上のファイルを参照できるのでおすすめです。
html_theme = 'furo'
(省略)
html_theme_options = {
"source_repository": "https://github.com/takanory/gihyojp-sphinx-sample/",
"source_branch": "main",
"source_directory": "source",
}
make htmlを実行すると以下のようにテーマが変わります。
画面右上の目とペンのアイコンをクリックするとGitHubのページに遷移します。
Furoテーマを適用¶
あとはドキュメントを書き進めたり、ファイルを追加したりと執筆を進めたらmake htmlで結果を確認を繰り返します。
ドキュメントの具体的な書き方についてはMyST ParserまたはreStructuredTextのドキュメントを参照してください。
Read the DocsでWebサイトを公開¶
ここまではドキュメントはPCのローカルにしか存在しませんでした。 ここからの手順で作成したドキュメントをインターネット上に公開し、誰でもアクセスできるようにしていきます。
アカウントを作成¶
Sphinxのドキュメントをホストするサービスはいくつかありますが、ここではRead the Docsを使用します。 Read the DocsはSphinxとMkDocsに対応した、静的サイトジェネレーターのドキュメントをビルドしてホスティングするサービスです。
Read the Docs: https://about.readthedocs.com/
Read the Docs documentation: https://docs.readthedocs.io/
アカウントが必要なのでSing upをクリックしてアカウントを作成します。 Publicリポジトリで公開ドキュメントであれば無料の「Read the Docs Community」でアカウントを作成します。
Read the Docs Communityでアカウントを作成¶
アカウント作成時に「Sign up with GitHub」を選択し、自身のGitHubアカウントを使用してアカウントを作成します。 GitHubにログインすると権限の許可を求められるので、内容を確認し「Authorize readthedocs」ボタンをクリックして権限を設定します。 この権限を設定することにより、GitHubから自動でビルドできるようになります。
Read the DocsにGitHubへのアクセス権限を設定¶
最後にメールアドレスを入力してアカウント作成は完了です。 次にプロジェクトを設定します。
プロジェクトを追加¶
Read the Docsの画面で「Import a Project」をクリックし、リポジトリの一覧からビルド対象のリポジトリを選択します。 ここでは言語は日本語なので「Japanese」を選択して「Next」をクリック、次の画面で「Finish」をクリックしてプロジェクトの追加は完了です。
「Your document is building」のリンクをクリックしてビルド状況を確認します。 ここでは設定が足りていないため、ビルドに失敗しています。
Read the Docsにプロジェクトを登録¶
警告
動画の横に ../_images/readthedocs03.mp4 のリンクがありますが、無視してください。謎
プロジェクトがビルドできるようにするために設定ファイルを追加します。
設定ファイルを追加¶
現在の状態ではRead the Docsのビルドに失敗し、以下の様なエラー画面が表示されます。
ビルドの失敗画面¶
エラーメッセージに「The required .readthedocs.yaml configuration file was not found at repository's root」とあるとおり、リポジトリのルートに .readthedocs.yaml という設定ファイルを配置する必要があります。以下の内容を記述してリポジトリにプッシュします。
# 必須
version: 2
# OSとPythonバージョンを設定する
build:
os: ubuntu-22.04
tools:
python: "3.12"
# source/ ディレクトリ以下のドキュメントをビルドする
sphinx:
configuration: source/conf.py
# requirements.txtのパッケージをインストールする
python:
install:
- requirements: requirements.txt
なお、設定ファイルの詳細な記述内容については、以下のドキュメントを参照してください。
再度ビルドを実行すると、ビルドに成功します。 画面右上の「View Docs」ボタンをクリックすると、ビルドされたHTMLを参照できます。
ビルドに成功¶
Read the Docsではビルドしたドキュメントを「リポジトリ名.readthedocs.io」というドメインで公開します。 この場合はhttps://gihyojp-sphinx-sample.readthedocs.io/というドメインにドキュメントがホスティングされるようになりました。
ビルドの失敗画面¶
以降はドキュメントを修正してリポジトリにプッシュすると、自動でドキュメントが更新されます。
Read the Docsでは独自ドメインなど、さまざまな設定が可能です。 詳細は設定画面やRead the Docsのドキュメントを参照してください。
他のホスティングの選択肢¶
SphinxドキュメントをビルドしてデプロイできるサービスはRead the Docs以外にもいくつかあります。 ここでは簡単に紹介します。 詳細な手順は以下のSphinxのドキュメントを参照してください。
GitHub Pages¶
GitHub PagesはGitHubが提供する静的ホスティングサービスです。 GitHubのリポジトリ上のHTMLファイルをホスティングできます。 GitHub Actionsと組み合わせることで、GitHubへのプッシュ時に自動ビルドが実行できるようになります。
Cloudflare Pages¶
Cloudflare PagesはCloudflareが提供するJAMstackプラットフォームですが、Sphinxのホスティングにも対応しています。 詳細な手順は以下のドキュメントを参照してください。
ただこの手順は少し古く、ビルドシステムを最新バージョンの 2 にすると、Python 3.7ではなくPython 3.10が使用できます。
また、pipenv ではなく pip を使用するようになるためPipfileは不要になり、requirements.txtのみが必要となります。
ビルドの構成 で以下のように記述するとビルドされます。
ビルド コマンド: make html
ビルド出力ディレクトリ: /build/html
ルート ディレクトリ: /
プルリクエストのビルドコメント: 有効
また、Cloudflare PagesとCloudflare ゼロトラストを組み合わせると、認証付きのページも作成できます。
Netlify¶
Netlifyも静的ホスティングサービスの1つです。 ただし、NetlifyのPythonバージョンはPython 3.8のため、最新のSphinxが使用できません。
Sphinxをさらに拡張¶
SphinxのドキュメントがRead the Docsで自動的にビルドされれるようになりました。 ここからは筆者おすすめの拡張機能を紹介します。
ぜひ拡張機能を上手に利用してドキュメントをよりよいものにしてください。 サードパーティーの拡張機能は以下のページで探すことができます。
Sphinx内蔵の拡張機能¶
Sphinxにはあらかじめ含まれている拡張機能があります。一覧は以下のページにあります。
おすすめの拡張に sphinx.ext.todo があります。sphinx.ext.todo はドキュメントをにTodoを入れられる拡張機能です。機能を有効にするにはconf.pyのextensionsに"sphinx.ext.todo"を追加します。
extensions = [
"myst_parser",
"sphinx.ext.todo",
]
# TODOを有効にする
todo_include_todos = True
あとは任意のページに以下の様に書いた項目がTODOとなります。
```{todo}
ソースコードを実際に動かして動作確認する
```
そしてトップページなどに以下の様に書いておくと、その位置にすべてのTODOが表示されます。
```{todolist}
```
ドキュメントをビルドすると、以下の様にTODOの一覧が表示されます（ここでは1件だけですが）。 ドキュメントであとで書く、確認することをTODOにしておくと、把握がしやすく便利です。
sphinx.ext.todo機能でTODOが表示される¶
sphinx-autobuild: ドキュメントを自動ビルド¶
sphinx-autobuildはSphinxのドキュメントが変更されたら、自動的にビルドをしてブラウザを再読み込みする拡張機能です。
Sphinxでドキュメントを執筆するときには、エディターで執筆→make htmlを実行してビルド→ブラウザで再読みこみを繰り返します。
この拡張機能を使うことで、エディターで編集して保存するだけであとの処理はsphinx-autobuildが実行してくれるようになります。
sphinx-autobuildをpipコマンドでインストールします。
(env) % pip install sphinx-autobuild
拡張機能をインストールするとsphinx-autobuildコマンドがインストールされるので、コマンドを以下のように実行します。
デフォルトでは8000番ポートでWebサーバーが起動するので、Webブラウザでhttp://127.0.0.1:8000/にアクセスすると、常に最新のドキュメントが表示されるようになります。
ポート番号を変更したい場合は--port 8001のように指定してください。
(env) % sphinx-autobuild source build/html
(env) % sphinx-autobuild source build/html --port 8001 # ポート番号を指定する場合
sphinx-design: デザインコンポートネント、アイコンを追加¶
sphinx-designはSphinxのドキュメントでグリッドレイアウトやドロップダウン、タブといたデザイン用のコンポーネントを追加します。
また、各種アイコンも追加します。
この拡張機能を使うには、他と同様にpipコマンドでインストールし、source/conf.pyに拡張機能として追加します。
(env) % pip install sphinx-design
extensions = [
"myst_parser",
"sphinx.ext.todo",
"sphinx_copybutton",
"sphinx_design",
]
筆者はこの拡張機能を、Font Awesomeのアイコンをドキュメントで表示する用途で使用しています。 Font Awesomeのアイコンを表示するには、source/conf.pyに以下の記述を追加します。 またMaterial Iconsも使用できます。
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css"
]
ドキュメントに以下の様に書くと、Font AwesomeとMaterial Iconsが使用できます。
## Font Awesome
* {fab}`twitter` [@takanory](https://twitter.com/takanory)
* 私は{fas}`music` が好きで、{fas}`beer-mug-empty`も好きです。
## Material Icons
* {material-regular}`headphones`はBOSEを使っています
* {material-regular}`pets`にはフェレットを飼っています
アイコンが表示される¶
sphinxext-opengraph: OGP(Open Graph Protocol)用のメタデータ、画像を生成¶
sphinxext-opengraphはOGP(Open Graph Protocol)用のメタデータ、画像を生成する拡張機能です。 これらの情報が適切に設定してあると、WebページをSNS等で共有したときに画像や説明文が適切に入るため、リンク先の内容がわかりやすくなります。
まずはpipコマンドでsphinxext-opengraphをインストールします。
また後述するソーシャルカードの自動生成のために、Matplotlibもインストールします。
(env) % pip install sphinxext-opengraph matplotlib
そしてsource/conf.pyで拡張機能として追加し、いくつか設定を記述します。
extensions = [
"myst_parser",
"sphinx.ext.todo",
"sphinx_copybutton",
"sphinx_design",
"sphinxext.opengraph",
]
# サイトURLとデフォルト画像を設定
ogp_site_url = "https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/"
ogp_image = "https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/_static/logo.png"
するとHTMLのヘッダーに以下の様にogタグが挿入され、SNS等でシェアしたときに画像や説明が入るようになります。
<meta property="og:title" content="gihyo.jp記事のSphinxサンプル" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://gihyojp-sphinx-sample.readthedocs.io/index.html" />
<meta property="og:site_name" content="Gihyojp Sphinx Sample" />
<meta property="og:description" content="このドキュメントは、gihyo.jpの Python Monthly Topis でのSphinx記事のサンプルドキュメントです。 Markdownで書いてます。 目次: sphinx.ext.todoのサンプル, sphinx-copybuttonのサンプル, sphinx-designのサンプル- Font Awesome, Material Icons.. TODOリスト:( 元のエン..." />
<meta property="og:image" content="https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/_static/logo.png" />
<meta property="og:image:alt" content="Gihyojp Sphinx Sample" />
<meta name="description" content="このドキュメントは、gihyo.jpの Python Monthly Topis でのSphinx記事のサンプルドキュメントです。 Markdownで書いてます。 目次: sphinx.ext.todoのサンプル, sphinx-copybuttonのサンプル, sphinx-designのサンプル- Font Awesome, Material Icons.. TODOリスト:( 元のエン..." />
ソーシャルメディアカードの生成¶
sphinxext-opengraphのさらに強力な機能に、ソーシャルメディアカードの生成があります。 この機能は、og:image用にページのタイトルや説明を埋め込んだ画像を、Matplolibを使用して生成するというものです。 機能の詳細は以下のページを参照してください。
ソーシャルメディアカードを生成するために、source/conf.pyに以下の設定を追加します。 デフォルトのフォントは英語のみに対応しているため、Read the Docsのサーバーにデフォルトでインストールされている日本語に対応したフォントを指定します（環境により変わります）。 また、ローカルのmacOSやWindowsでの実行時にエラーにならないように、フォントの設定を変更するコードも入れておきます。
# ogp_imageオプションはコメントアウト
# ogp_image = "https://gihyojp-sphinx-sample.readthedocs.io/ja/latest/_static/logo.png"
# ソーシャルカード用の画像とフォントの設定
ogp_social_cards = {
"enable": True,
"image": "_static/logo.png",
"font": "Noto Sans CJK JP",
}
# macOSとWindows用のフォント設定
if sys.platform == "darwin":
ogp_social_cards["font"] = "Hiragino Maru Gothic Pro"
elif sys.platform == "win32":
ogp_social_cards["font"] = "MS Gothic"
ソーシャルメディアカードが生成されると、ヘッダーのog:imageのURLが以下の様なランダムな文字列を含んだ画像ファイル名になります。
<meta property="og:image" content="https://gihyojp-sphinx-sample.readthedocs.io/_images/social_previews/summary_index_cda79cf9.png" />
各SNSで実際にどのように表示されるかを、www.opengraph.xyzというサイトにURLを入力して確認します。 すると、以下の様にソーシャルカードが生成され、プレビューがわかりやすくなったことがわかります。
www.opengraph.xyzで結果をプレビュー¶
og:imageの画像は以下の様な内容です。 このような画像がページごとに生成され、それぞれタイトルや説明文が入ります（ロゴ画像とタイトルがかぶってしまってますが）。
トップページのog:image画像¶
sphinx-comments: コメント機能を追加¶
Sphinx CommentsはSphinxのWebサイトにコメント機能を追加する拡張機能です。 書籍のレビューやプレビュー版のWebサイトに対して、SphinxのWebページ上でコメントができるようになります。 コメントの書き込み、保存する機能には外部サービスを使用しています。 ここではHypothesisという、インターネット上の任意のページに注釈を付けられるサービスを使用します。
pipコマンドでsphinx-commentsをインストールし、source/conf.pyに設定を追加します。
(env) % pip install sphinx-comments
extensions = [
"myst_parser",
"sphinx.ext.todo",
"sphinx_copybutton",
"sphinx_design",
"sphinxext.opengraph",
"sphinx_comments",
]
# コメントをHypothesisでする
comments_config = {
"hypothesis": True
}
拡張機能が有効になると、画面右上にコメントを表示する欄を開くためのアイコンが表示されます。 また、ページ内を選択するとその箇所に対してコメントが書けます。
sphinx-commentsでページにコメントを追加¶
警告
動画の横に ./_images/sphinx-comments.mp4 のリンクがありますが、無視してください。謎
なお、コメントを書き込むにはHypothesisのアカウントが必要となります。 また、書き込んだコメントとURLはHypothesisサイト上で誰でも参照できるため、秘密の情報を書かないように注意してください。
sphinx-revealjs: プレゼンテーション資料を作成¶
sphinx-revealjsはSphinxのドキュメントからプレゼンテーション用のHTMLを生成する拡張機能です。 内部的にはreveal.jsというJavaScriptのフレームワークを使用しています。
sphinx-revealjsを使用するにはpipコマンドでインストールしてsource/conf.pyに設定を追加します。
(env) % pip install sphinx-revealjs
extensions = [
"myst_parser",
"sphinx.ext.todo",
"sphinx_copybutton",
"sphinx_design",
"sphinxext.opengraph",
"sphinx_revealjs",
]
設定が完了するmake revealjsコマンドが使用できるようになります。
コマンドを実行するとbuild/revealjs/フォルダにスライドのHTMLが生成されます。
(env) % make revealjs
Webブラウザでbuild/revealjs/index.htmlを表示すると、以下の様なプレゼン資料が表示されます。 第2レベル、第3レベルの見出し単位でスライドが作成されます。
生成されたスライドを表示¶
具体的なスライドの表示イメージは公式ドキュメントの以下のスライドを参照してください。
なお、筆者は最近のプレゼン資料はすべてsphinx-revealjsで作成しています。 ぜひ参考にしてみてください。
GitHubリポジトリ: takanory/slides: presentation slides
ビルドしたWebサイト: takanory slides
まとめ¶
本記事の前半ではSphinxを使ってMarkdownで書いたドキュメントからWebサイトを構築し、外部へ公開する流れについて紹介しました。 そして後半ではSphinxをさらに便利にするおすすめの拡張機能を紹介しました。
本記事で紹介したSphinxや拡張機能の設定や使い方は、それぞれのほんの一部です。 さらに詳細な設定や使い方については、それぞれの公式ドキュメントを参照してください。
名前 |
公式ドキュメント |
|---|---|
Sphinx |
|
MyST Parser |
|
Furo |
|
Read the Docs |
|
sphinx-autobuild |
|
sphinx-copybutton |
|
sphinx-design |
|
sphinxext-opengraph |
|
sphinx-comments |
|
sphinx-revealjs |
また、筆者が出演しているYouTube PyCon JP TVで、本記事の一部の手順を実際にライブデモで見せている動画があります。 実際にコマンドを入力して動作しているところ見た方がイメージが湧きやすい部分もあると思います。 こちらも参考にしてみてください（20:42からライブデモをしています）。
Sphinxの使いこなしについてはSphinx-users.jpの情報も参考になります。 また、毎月イベントを開催しているので、そちらに参加してみると知見が得られるかも知れません。
ドキュメントを中心としたWebサイトを構築したいときには、ぜひSphinxにチャレンジしてみてください。