Software-Dokumentation mit Sphinx: Zweite ueberarbeitete Auflage (Sphinx 2.0)
目次
- 目次
- はじめに
- Sphinx
- reStructuredTextでよく使う表現
- GitHubリポジトリのドキュメントやコードから生成されたドキュメントをgithub pagesで公開する
- SphinxのページにGoogle AnalyticsやGoogle Adsのコードを埋め込む
- ソフトウェアドキュメントの構成
- ソフトウェアドキュメントを書くコツ
- 参考資料
- MyEnigma Supporters
はじめに
著名なOSSを見るとそのOSSのオンラインドキュメントも、
ソースコードと同じgitリポジトリで
管理されていることが多いです。
そのような、テキストベースで
オンラインドキュメントを作成できるツールとして有名なのが、
Pythonで作られているのSphinxです。
Sphinx
Sphinxは、Python製のドキュメント生成ツールです。
デフォルトでは、reStructuredTextというテキストフォーマットから、
下記のような整形されたドキュメントを生成できます。
- HTML
- EPUB
- man pages
拡張機能を使うことで、Markdownから上記のドキュメントを生成することが可能です。
またautodocという機能を使うことで、
Pythonコードのdocstringを自動的に認識して
簡単にAPIリファレンスを作ることができます。
Sphinxはそのような便利機能があるため、
下記のような
有名なOSSのオンラインドキュメントで採用されています。
reStructuredTextでよく使う表現
セクション(章立て)
マークダウンの場合、セクションはシャープの数で指定しますが、
RSTでは、セクションのタイトルの下に、記号で線を引けます。
様々な記号をつかってもSphinxが自動的にセクションを自動的に設定してくれますが、
独自にルールを作って、線を引いたほうが良いでしょう。
自分は下記のようなルールを使っています。
セクション(レベル１) ===================== レベル２ --------- レベル３ ~~~~~~~ レベル４ ^^^^^^^^
セクションの名前よりも、線が短いとSphinxがワーニング出すので注意が必要です。
各セクションをリンクする場合
下記の記事にある通り、同じファイル内で定義されているセクションの場合は、”.. _My target:"でタグを付けて、
"`My target`_."で、リンクを作成できます。
他のファイルで定義されているセクションをリンクする場合は、
下記の回答にある通り、:ref:`My target`でリンクすることができます。
URLをリンクする場合
下記のようにリンクを作成できます。
`Sphinxを知りたい方はこちらをクリック <http://sphinx-users.jp>`_
数式のナンバリングと参照
こちらの記事の通り、:label: eulerで数式にラベルをつけて、
:eq:eulerで参照できます。
sphinx_rtd_themeを使っていて、数式番号が変なところに表示される場合
sphinx_rtd_themeの既存のバグのようです。
こちらのコミットのように、カスタムCSSを設定すると修正されます。
includeしたrstファイルで数式のラベルが重複しているとワーニングが出る
これは、こちらのコメントにある通り、cont.pyで設定しているsource_suffixに
includeしたファイルが含まれた場合、build時にそのファイルが検索され、読み込まれ、
親のファイルからincludeで読み込まれて、二重に読み込まれることになるからです。
対策として、各セクションのrstのファイルは、*_main.rstとして、
source_suffixは"main.rst"と設定するようにしました。
画像を表示する
下記の記事の通り、そのファイル化から画像ファイルへのパスを設定すると
画像を表示することができます。
.. image:: static/img/sphinx.png
GitHubリポジトリのドキュメントやコードから生成されたドキュメントをgithub pagesで公開する
こちらのGitHub Actionを使うのがおすすめです。
こちらのGitHub Actionを設定しておくと、
masterブランチにマージされるたびに、
生成されたドキュメントをgh-pages branchにpushしてくれるため、
あとは、リポジトリの設定から、
gh-pagesのrootディレクトリにgithub pagesの登録するように設定すればOKです。
SphinxのページにGoogle AnalyticsやGoogle Adsのコードを埋め込む
下記の記事のように、layout.htmlを拡張することで埋め込むことが可能です。
どのblockを拡張するかはそれぞれのthemeによって代わりますが、
ReadTheDocのthemeを使っている場合は、下記の元のlayout.htmlを見れば、
どのようなBlockが定義されているかわかるはずです。
ソフトウェアドキュメントの構成
ソフトウェアのドキュメントは、
下記の3つで分けると見通しがよくなります。
設計ドキュメント(DESIGN.md, ARCHITECTURE.md)
アーキテクチャの情報や、
クラス図やデータベースのダイアグラムのような低水準の設計情報を提供するドキュメント
主にそのソフトウェアの開発者が読む。
使用方法 (HOW_TO_USE.md, RECIPE.md, TUTORIAL.md)
ソフトウェアをどのように使用するのかが書かれたドキュメント。
このドキュメントは、クックブック、チュートリアル、モジュールレベルのヘルプなどの形態で提供される。
主にそのソフトウェアのユーザが使う。
運用 (DEPLOYMENT.md)
デプロイやアップグレード、ソフトウェアの運用に関するガイドラインを提供する
主にそのソフトウェア を運用する人が使う。
ソフトウェアドキュメントを書くコツ
毎回2行だけ文章を書き、読み返して修正するというものです。
こうすることで、文章の作成とテキストのスタイルの両方にフォーカスできます。
参考資料
planset-study-sphinx.readthedocs.io
MyEnigma Supporters
もしこの記事が参考になり、
ブログをサポートしたいと思われた方は、
こちらからよろしくお願いします。
