📝Sphinx

📝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/

参照 #

参考文献 #


Tags