sphinx-usage.md

.. index::
    pair: Sphinx; usage

Sphinxの使い方

SphinxはreStructredText（reST） 形式で作成された文書を、PDFやHTML、その他のフォーマットへと変換してくれるドキュメンテーションビルダーというツールです。 Pythonのドキュメント生成のために開発されたものなので、プロジェクトのドキュメント作成にはもってこいです。 また、中身もPythonで書かれているので、へびつかいであれば、ある程度カスタマイズすることもできるはずです。

このKumaROOTもSphinxを使って生成しています。 プロジェクト自体はGitHubを使ってバージョン管理をしてあり、ウェブ版はRead the Docsで公開しています。 どういったものか気になる方はぜひKumaROOTのGitHubリポジトリをクローンしてみてください。

はじめたい

ドキュメントのはじめかたや、拡張パッケージの設定方法などを整理しました。

---
maxdepth: 1
---
sphinx-install
sphinx-quickstart
sphinx-conf
sphinx-conf-numfig
sphinx-conf-today-fmt
sphinx-extensions

拡張機能したい

僕がよく使う拡張機能を紹介します。

---
maxdepth: 1
---
sphinx-extensions-myst
sphinx-extensions-opengraph
sphinx-extensions-googleanalytics
sphinx-extensions-copybutton
sphinx-extensions-ablog
sphinx-extensions-datatemplates
sphinx-extensions-napoleon

マークアップしたい

ドキュメントをマークアップする方法を整理しました。 Sphinxの基本はディレクティブ（directive）とロール（role）です。

:::{hint}

ディレクティブ／ロールは、 HTMLだとブロック要素／インライン要素、 LaTeXだと環境／コマンド、 に相当するイメージで、僕はドキュメントをマークアップしています。

:::

デフォルトの基本はreST（reStructuredText）記法なのですが、 このドキュメントではMyST記法を前提にコードのサンプルを例示します。

---
maxdepth: 1
---
sphinx-syntax-toctree
sphinx-syntax-comment
sphinx-syntax-hyperlink
sphinx-syntax-code-block
sphinx-syntax-admonition
sphinx-syntax-image
sphinx-syntax-meta
sphinx-syntax-footnote
sphinx-syntax-include
sphinx-syntax-index

HTMLしたい

---
maxdepth: 1
---
sphinx-html-theme
sphinx-html-title
sphinx-html-logo
sphinx-html-htaccess
sphinx-html-sidebars
sphinx-html-css

% あとでsphinx-designのページを作る % sphinx-html-sd

LaTeX / PDFしたい

---
maxdepth: 1
---
sphinx-latex-engine
sphinx-latex-docclass
sphinx-latex-elements
sphinx-latex-documents
sphinx-latex-logo
sphinx-latex-section
sphinx-latex-thesection

---
maxdepth: 1
caption: 設定例
---
sphinx-latex-lualatex
sphinx-latex-uplatex

ビルドしたい

ドキュメントをビルドする方法を整理しました。

---
maxdepth: 1
---
sphinx-build
sphinx-build-html
sphinx-build-latexpdf
sphinx-build-linkcheck
sphinx-build-gettext
sphinx-autobuild

デプロイしたい

---
maxdepth: 1
---
sphinx-deploy-gitlab
sphinx-deploy-rtd