Open14

PyData Sphinx Theme

テーマを変更する

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

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

  • ナビゲーション(トップバー)の右に関連サイトへのリンクとアイコンを追加する
  • GitLabリポジトリとTwitterのリンクを追加した
conf.py
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 で書いておくことにした

外部リンクを追加する

  • ナビゲーション(トップバー)に外部リンクを追加する
conf.py
html_theme_options = {
    ...,
     "external_links": [
         {"name": "JACST", "url": "https://sites.google.com/view/jacst"},
     ],
    ...,
}
  • nameurl のキーを設定する
  • 複数設定することができる

ファビコンを追加する

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

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

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

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

  • デフォルトで有効になっているので、このままでOK
conf.py
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を設定しないとビルド時にエラーになる
conf.py
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 ..."
  • 日本語にしておく
conf.py
html_theme_options = {
    ...,
    "search_bar_text": "全文検索する",
    ...,
}

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

  • デフォルトは copyrightsphinx-version を表示する
  • footer_items に最終更新日(last-updated.html)のテンプレートを追加する
conf.py
html_theme_options = {
    ...,
    "footer_items": ["copyright", "sphinx-version", "last-updated"],
    ...,
}

日本語訳がイマイチ?

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

テンプレートを検索する

mdfind
$ mdfind last-updated.html
/usr/local/lib/python3.9/site-packages/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/last-updated.html
last-updated.html
<p class="last-updated">
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br>
</p>
  • 翻訳ファイルをどこかにおけばいいのか?
  • このテンプレートをコピーして、カスタマイズしたほうがいいのか?
  • 結局 last_updated はどこで設定されるのか?

最終更新日

  • conf.pyhtml_last_updated_fmtを設定すると表示されるようになった
conf.py
...
html_last_updated_fmt = "%Y-%m-%d"
...

サイドバー(左)の表示を変更する

  • サイドバーは Sphinx の機能である html_sidebars を使っている
  • 対象とするページごとにサイドバーの表示内容を設定することができる
conf.py
html_sidebars = {
    "対象となるページ": ["テンプレート1", "テンプレート2", "テンプレート3"]
}
  • ページ指定に glob-pattern を使うこともでき、デフォルトは以下の通り
conf.py
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 = ?
ログインするとコメントできます