sphinx-quickstartコマンドを対話的に使わない（必要な引数を含めたマシマシ呪文詠唱！）

はじめに

一方通行＜アクセラレータ＞！ nikkieです。

ドキュメンテーションツールSphinxには、ひな形となるディレクトリ構造を作ってくれるsphinx-quickstartコマンドがあり、とても便利です。
私はこれを対話的に使わないという使い方をしています。

目次

対話的に使えるsphinx-quickstartコマンド

『Sphinxをはじめよう』の3.2に例があります

対話的に設定するのは以下の項目

• ソースディレクトリとビルドディレクトリを分けるかどうか
  • ソースディレクトリに原稿（reSTやMarkdownなどのファイル）を置きます
  • ビルドディレクトリにはSphinxがビルドしたHTMLやPDFが置かれます
  • -> 私は分けています
• プロジェクト名
• 著者名
• リリース番号
• 言語設定

この入力に基づき、ディレクトリやファイルが自動生成され、空の原稿がビルドできる状態になります。

行き着いたアプローチ：必要な引数を全部渡すことで、対話をスキップする

当初は対話的に使っていたのですが、対話的に入力した設定値が思い出せないことがありました。
これに対処するため、sphinx-quickstartコマンドのドキュメントを確認し、必要な引数を全部渡す使い方に切り替えました。

引数込みのコマンドを控えておけば、プロジェクトが変わっても同じように最初の自動生成ができます。
例えば、sphinx-revealjsで作ったスライド¹のリポジトリなら、こんなコマンドです

sphinx-quickstart \
  --sep \
  -p 2023_slides \
  -a nikkie \
  -r '' \
  -l ja \
  --no-batchfile \
  --ext-githubpages \
  --extensions sphinx_revealjs \
  --extensions sphinx_design

• --sep：ソースディレクトリとビルドディレクトリを分ける指定
• -p：プロジェクト名
• -a：著者名
• -r：リリース番号
  • 空文字列を渡していますが、そもそも指定しなくてもいいかもしれないですね
• -l：言語設定

さらに以下のオプションも追加しました。
最後の2つはsphinx-quickstartが作るconf.pyに加筆せずに使いたいという怠惰さから来ています。

• --no-batchfile
  • 動かす環境がmacOS（開発マシン）またはLinux（GitHub Actionsでビルド）なので、不要なbatファイルを作っていません
• --ext-githubpages
  • GitHub Pagesで公開するのに必要なsphinx.ext.githubpages拡張²を有効にしています
• --extensions
  • これは複数指定でき、conf.pyのextensions（リスト）に指定する文字列を列挙しています³

いずれもオプションも、詳しくは上記のsphinx-quickstartコマンドのドキュメントをどうぞ

今回知った、対話スキップの-qオプション

アウトプットに当たり調べたところ、sphinx-quickstart -qで対話ウィザードをスキップできるという情報が見つかりました⁴。
https://www.sphinx-doc.org/ja/master/man/sphinx-quickstart.html#cmdoption-sphinx-quickstart-q

なるほど、スキップするオプションがあったんですね！
Sphinxユーザ会の「Sphinxをはじめよう」でも紹介されています

(略) -q オプションを付けると非対話モードでプロジェクトが作成できます。ここでは非対話モードを紹介します。

ドキュメントによると、-qオプションと一緒に以下の3つを指定する必要があります⁵

• -p（上で見たプロジェクト名）
• -a（上で見た著者名）
• -v：プロジェクトのバージョン
  • https://www.sphinx-doc.org/ja/master/man/sphinx-quickstart.html#cmdoption-sphinx-quickstart-v
  • 私はいつも指定していなかったわけですが、手元で試したところ、空文字列でもよさそうでした

sphinx-quickstart \
  -q \
  -p 2023_slides \
  -a nikkie \
  -v '' \

この最小構成のコマンドに、上で紹介したオプションをマシマシにしていけばよさそうですね。

今後はこんな感じのコマンドを使っていこう

sphinx-quickstart \
  -q \
  -p 2023_slides \
  -a nikkie \
  -v '' \
  -l ja \
  --sep \
  --no-batchfile \
  --ext-githubpages \
  --extensions sphinx_revealjs \
  --extensions sphinx_design

終わりに

sphinx-quickstartコマンドをあえて対話的に使わない方法を見てきました。
今回爆誕した引数マシマシの呪文を詠唱して、Sphinxを使うときのディレクトリ構造は再現できるでしょう！

なお、上記のコマンドは、Python 3.12.0・Sphinx 7.2.6で動作確認しています

---

1. sphinx-revealjsを愛用しており、GitHub Pagesで公開しています。↩
2. ありがとう、sphinx.ext.githubpages。 ↩
3. sphinx_designについてはこちらをどうぞ ↩
4. 「Quiet mode that skips the interactive wizard for specifying options.」ref: https://www.sphinx-doc.org/ja/master/man/sphinx-quickstart.html#cmdoption-sphinx-quickstart-q↩
5. 「This option requires -p, -a and -v options.」 ref: https://www.sphinx-doc.org/ja/master/man/sphinx-quickstart.html#cmdoption-sphinx-quickstart-q↩