🔥虚無との戦い

📝Sphinx

5 min read

Sphinxとは

Python製のドキュメント作成エンジン及びサイト.

Sphinx Tips

howto: SphinxのThemeを変更するには?

read: テーマの変更 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

tip: MarkdownでSphinxドキュメントを書く方法

MyST-Parserという拡張を利用する.

note: recommonmarkを使う方法は情報が古い(2021)

links

tip: Emacs Org-modeでSphinxドキュメントを書く方法

howto: Emacs Org-modeからreSTファイルを生成するには?

ox-rstをつかう(https://github.com/msnoigrs/ox-rst).

org-exportの項目としてreSTへの出力を組み込むことができる.または，M-x org-rst-export-to-rst コマンドでOrg fileをreST file変換して出力することが可能.

ox-rstで出力されるフォーマットを細かく設定するには，org-modeのexport設定をする必要がある(https://orgmode.org/manual/Export-Settings.html).

たとえば，

  • author:nilで, authorのexportを抑止.
  • num:nilで, headlineのナンバリングを抑止.
#+OPTIONS: author:nil num:nil

howto: ox-rstをCLIから実行するには?

emacsをバッチモード

emacs $1 --batch --eval="(load \"~/.emacs.d/.local/straight/repos/ox-rst/ox-rst.el\")" -f org-rst-export-to-rst --kill

link: https://github.com/msnoigrs/ox-rst/issues/55#issuecomment-917417497

howto: Emacs Org exportのフォルダを指定するには?

EXPORT_FILE_NAME をファイルヘッダに設定する.

#+EXPORT_FILE_NAME: ~/repo/futurismo-wiki/sphinx.rst

howto: Org fileの中にSphinxの文法を書くには?

BEGIN_EXAMPLE rst を書く.

— #+BEGIN_EXPORT rst — .. class:: alert — #+END_EXPORT

howto: SphinxをNetlifyにHostingするには?

Sphinxはビルドで生成される~_build/html~をそのまま公開すればNetlifyでホスティングできる. この方法の嬉しいところは，Netlifyを利用することでホスティングが無料でできるということだ.

base directoryに requirements.txtとruntime.txtを配置する.

$ cat requirements.txt
sphinx
 
$ cat runtime.txt
3.8

あとは，~sphinx-build {source dir} {dest dir}~のコマンドを実行すると，_build/html相当のものが{dest dir}にできる. これを，Deploy settingsのbuild commandに設定すればよい.

link: Manage build dependencies | Netlify Docs

notes: package.jsonをつかった自動化の例

参考までに，わたしはpackage.jsonを配置することで，npm scriptでビルドを走らせることにした.

{
  "scripts": {
    "hugo": "hugo",
    "wiki": "sphinx-build wiki public/wiki",
    "deploy": "npm run hugo && npm run wiki"
  }
}

howto: SphinxにGoogle Analyticsを埋め込むには?

テーマのlayout.htmlをコピーしてオリジナルのlayout.htmlを作成する.

rootの下の_templatesにlayout.htmlというファイルを作り下記のように記載.

{%- extends "!layout.html" %}
 super() 
{%- block extrahead %}
<!-- ここにGoogle Analyticsタグ追加 -->
{% endblock %}

link: Google Analyticsのタグを埋め込む — Sphinxを使ってみよう

howto: SphinxのページにGoogle Adsenseを貼り付けるには?

基本的には(howto: SphinxにGoogle Analyticsを埋め込むには?)に同じ. rootの下の_templatesに上書きしたいhtmlを作成する.

link: Google AnalyticsやGoogle Adsenceを貼りたい - Sphinxの日本ユーザ会

example: page.htmlやsearchbox.htmlの継承

たとえば，私の場合は Sphinx Basic Theme を利用しているので，GitHubから上書きしたpage.htmlとsearchbox.htmlをそれぞれコピーして_templates配下に配置して，以下のようにGoogle Adsenseのコードを追加した. 以下はpage.htmlの例.

{%- extends "layout.html" %}
{% block body %}
   body 
  <!-- ここにGoogle Adsenseタグ追加 -->
{% endblock %}

howto: Sphinxにサイトマップ(sitemap.xml)を追加するには?

sphinx-sitemapというextentionsを使う.

link: https://pypi.org/project/sphinx-sitemap/

Insights

✨Sphinxのキモは骨子構造にあり

骨子(こっし)構造はSphinx独特の表現かもしれない. 📝ストーリーラインともいう.

グラフビュー

バックリンク

Recents