Sphinx

• 言語: Python
• テンプレート形式: Jinja2
• コンテンツ形式：reStructuredText, Markdown

https://www.sphinx-doc.org/en/master/

インストール

$ pip3 install sphinx

$ pipx install sphinx

$ uv tool install sphinx

$ brew install sphinx-doc

• Homebrewのフォーミュラ名はsphinx-docになっている
• 以前はsphinxという音関係のツールがあったけど、いまはなくなっている

新規作成

$ sphinx-quickstart PROJECT_DOCS

$ sphinx-quickstart PROJECT_DOCS --sep --language ja --suffix .md

プロジェクトにドキュメントを追加する

$ cd プロジェクト名
$ poetry init
$ poetry add --group=docs sphinx
$ poetry add --group=docs myst_parser
$ poetry add --group=docs sphinx_rtd_theme
$ sphinx-quickstart docs

• PythonのパッケージはPoetryで管理する前提
• ドキュメント関係のパッケージは--group=docsに追加する（--group=devでも--groupをつかなくてもいい）
• ドキュメントはプロジェクト名/docsに作成する

テーマを変更する

• sphinx_rtd_theme から pydata_sphinx_theme に変更してみたい
• さらに sphinx_book_themeに変更したい

$ pip3 install pydata_sphinx_theme

$ code .
# （conf.pyを編集する）
# html_theme = 'pydata_sphinx_theme'

$ make html
# 特にエラーも出ずにHTMLをビルドすることができた

• ビルドすることはできたが、見た目の調整が必要な部分はある
• テーマの設定のドキュメントを読みながら確認する

ユーザーガイド

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/index.html

リンクとアイコンを追加する

• ナビゲーション（トップバー）の右に関連サイトへのリンクとアイコンを追加する
• GitLabリポジトリとTwitterのリンクを追加した

html_theme_options = {
    ...,
     "icon_links": [
         {
             "name": "GitLab",
             "url": "https://gitlab.com/jacst/goodpractice/",  # required
             "icon": "fab fa-gitlab",
             "type": "fontawesome",  # Default is fontawesome
         },
         {
             "name": "Twitter",
             "url": "https://twitter.com/jacst_jp",
             "icon": "fab fa-twitter",
         },
     ],
    ...,
}

• いつもの通り html_theme_optionsに設定を追記する
• name / url / icon / type のキーで設定する
  • url は必須項目
  • iconは FontAwesome のクラス名を探してくる
    • ローカルのアイコン画像を設定することもできる

リンクとアイコンのショートカット

• よく使われているサービスには設定用のショートカット名がある
  • GitHub / GitLab / BitBucket / Twitter
• 将来的に、この機能は削除されるかもとドキュメントに書いてあったので、 icon_links で書いておくことにした

外部リンクを追加する

• ナビゲーション（トップバー）に外部リンクを追加する

html_theme_options = {
    ...,
     "external_links": [
         {"name": "JACST", "url": "https://sites.google.com/view/jacst"},
     ],
    ...,
}

• name と url のキーを設定する
• 複数設定することができる

ファビコンを追加する

• faviconsを追加することができる
• まずファビコン画像を作らないといけない・・・

前のページ／次のページのナビゲーションを表示する

• デフォルトで表示ONになっているので、このままでOK

キーボードを使ったページ移動

• デフォルトで有効になっているので、このままでOK

html_theme_options = {
    ...,
    "show_prev_next" : True,
    "navigation_with_keys" : True,
    ...,
}

ページ編集ボタンを追加する

• リポジトリの編集用ページを開いて、閲覧者が修正の提案をできるようにする
• 2箇所に設定を追加する必要がある
  • html_theme_optionsの中に use_edit_page_button をセットする
  • conf.pyの中にhtml_contextの設定を追加する
• html_contextを設定しないとビルド時にエラーになる

html_theme_options = {
    ...,
     "use_edit_page_button": True,
    ...,
 }

html_context = {
     # "gitlab_url": "https://gitlab.com", # or your self-hosted GitLab
     "gitlab_user": "jacst",    # ユーザー名／団体名
     "gitlab_repo": "goodpractice",    # プロジェクト名
     "gitlab_version": "master",    # ブランチ名
     #"doc_path": "<path-from-root-to-your-docs>",
 }

• gitlab_user / gitlab_repo / gitlab_version は必須だった
• doc_path はなくてもOKだった（何を設定すべきなのかイマイチ分かってない）
• 何回かビルドを試しながら編集ページが開くかどうかを試せばOK

検索ボックスを設置する場所

• デフォルトではサイドバーに設置されている
• ナビゲーション（トップパー）に変更することもできる
• とりあえずデフォルトのままでOK

検索ボックスのテキストを変更する

• デフォルトは "Search the docs ..."
• 日本語にしておく

html_theme_options = {
    ...,
    "search_bar_text": "全文検索する",
    ...,
}

フッターの表示内容を変更する

• デフォルトは copyright と sphinx-version を表示する
• footer_items に最終更新日（last-updated.html）のテンプレートを追加する

html_theme_options = {
    ...,
    "footer_items": ["copyright", "sphinx-version", "last-updated"],
    ...,
}

日本語訳がイマイチ？

• 最終更新: None と表示されてしまう
  • 最終更新日: としたい
  • 日付をどこで取ってきてるのか？

テンプレートを検索する

$ mdfind last-updated.html
/usr/local/lib/python3.9/site-packages/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/last-updated.html

<p class="last-updated">
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br>
</p>

• 翻訳ファイルをどこかにおけばいいのか？
• このテンプレートをコピーして、カスタマイズしたほうがいいのか？
• 結局 last_updated はどこで設定されるのか？

サイドバー（左）の表示を変更する

• サイドバーは Sphinx の機能である html_sidebars を使っている
• 対象とするページごとにサイドバーの表示内容を設定することができる

html_sidebars = {
    "対象となるページ": ["テンプレート1", "テンプレート2", "テンプレート3"]
}

• ページ指定に glob-pattern を使うこともでき、デフォルトは以下の通り

html_sidebars = {
    "**": ["search-field", "sidebar-nav-bs", "sidebar-ethical-ads"]
}

• search-field : 検索ボックス
• sidebar-nav-bs : （テンプレートの内容を確認してもよく分からなかった）
• sidebar-ethical-ads : Read the Docs で公開するときに有効になるテンプレートのようだ

Admonition の日本語訳を調べた

• このテーマに特有のものではなく reSTのディレクティブ

https://docutils.sourceforge.io/docs/ref/rst/directives.html#attention

• attention = 注意／黄
• caution = 注意／黄
• danger = 危険／赤
• error = エラー／赤
• hint = ヒント／緑
• important = 重要／緑
• note = 注釈／青
• tip = ちなみに／青
• warning = 警告／黄
• admonition = ?

ディレクティブ

https://www.sphinx-doc.org/ja/master/usage/restructuredtext/directives.html

• toctree::
• code-block:: [language]
• math::

ロール

https://www.sphinx-doc.org/ja/master/usage/restructuredtext/roles.html

• :any:ラベル名 or ファイル名　自動クロスリファレンス。:doc: / :ref: / :option:を自動で判別してくれる
• :ref:ラベル名　自由な場所へのクロスリファレンス
• :doc:ファイル名　ドキュメントへのクロスリファレンス
• :download:ファイル名　ダウンロード可能なファイルへの参照
• :numref:ラベル名　図表番号へのクロスリファレンス
• :envbar:環境変数　環境変数
• :keyword:キーワード名　Pythonのキーワード名へのクロスリファレンス
• :option:オプション名　実行ファイルのコマンドラインオプション
• :term:用語　用語集への参照。用語集に説明がない場合は、ビルド時に警告が出力される
• :math:LaTeXの数式　数式をインラインで表示
• :eq:ラベル名　数式番号への参照（:math:numref:と同じ）
• :command:コマンド名　コマンド名を強調表示
• :file:相対パス or 絶対パス　ファイルやディレクトリの名前を強調表示
• :guilabel:UIにあるテキスト　UIの一部のラベル
• :kbd:キーボード操作　キーボード操作
• :program:実行プログラム名　実行プログラムの名前。拡張子は省略したほうがよい
• :regexp:正規表現　正規表現。引用符は含めることができない
• |release|　プロジェクトのバージョン番号（完全はバージョン文字列）
• |version|　プロジェクトのバージョン番号（メジャー.マイナー）
• |today|　今日（＝ビルドした日）の日付

数式ディレクティブ（math）

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#math

align環境を使ったらPDFのビルド（make latexpdf）でエラーが出たので、mathの使いかたを確認した

• 数式ディレクティブを使うと、LaTeXで数式を書くことができる
• 数式を複数行並べることができる。その場合は空行（blank line）を挿入する
• 数式はsplit環境の中に記述されるので、&と\\を使って整列できる
• デフォルトで数式番号は非表示。番号をつけたい場合はlabelオプションを使う。:eq:ラベル名（または:math:numref:ラベル名のロールで参照できる
• デフォルトで折り返されるがnowrapオプションで無効にできる

ということで、デフォルトでsplit環境が使われるのでalign環境を記述してしまうとエラーがでることがわかった。

Markdownを使えるようにする

extensions = ["myst_parser"]

# --- Options for MyST Parser -----
myst_enable_extensions = [
    "amsmath",
    "attrs_inline",
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
    # "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]

• MyST Parserを使ってMarkdownを使えるようにする
• オプションは（ほぼ）すべて有効にする
  • linkifyは別パッケージを追加する必要があったので、とりあえず除外した

気になるテーマ

• sphinx_rtd_theme
• sphinx_book_theme
• pydata_sphinx_theme
• ablog

これらのテーマのtheme.confを眺めてみる