1.はじめに
タイトルの「最小の労力で」とはsphinxを使うと最小の労力でドキュメントを作れますよという意味ではなく，sphinxを最小の労力で使いたいという意味です．
今回sphinxをコードのドキュメント作成ではなくどちらかというと本作成のような用途で初めて使ってみました．そのため，最低限これだけ押さえておけばそれっぽくなったよというメモです．
ドキュメントも全部日本語化されているので頑張ればなんとかなるとは思うが，そんなに時間を使いたくないので最小限でポイントを押さえたいという人向け．
2.sphinxとは
reSTというマークアップ言語で書かれたドキュメントを，texファイルに変換，htmlに変換をしてくれます．
他にも色々できそうですが，この記事の目的としてはこの定義で良いでしょう．
sphinxとはなんぞやについては以下が参考になる．
Sphinx ではじめるドキュメント生活 2012 #pyconjp #sphinxconjp
3.reSTとは
メインストリームはmarkdownに取られているものの，pythonコミュニティでひっそりと（？）長く使われてきたマークアップ言語らしい．
reSTとはなんぞやについては以下が参考になる．
技術ドキュメンテーションのためのreStructuredTextとMarkdownを比較する | POSTD
4.環境
- macOS sierra 10.12.6
- macTEX 2018
- python 3.6.0
- Sphinx 1.7.4
5.インストール
pythonで作られておりpipで入る．
$ pip install Sphinx
6.プロジェクトの作成
ドキュメントを作りたいディレクトリで以下を実行する．
$ sphinx-quickstart
詳細はここを参照すると良いが，文章が表示されるのでそれに受け答えていくだけでOK．
プロジェクトを作る — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
ちなみにその受け答えではプロジェクト名とか著者名を入力する．
それ以外は基本的にデフォルトで良い．
Separate source and build directories (y/n) [n]:
はyesの方がディレクトリが散らからないので良い．
7.conf.pyの設定
conf.pyに，htmlに出力する時の設定や，latexに出力する時の設定などを記述する．
詳細はここを参照する．
ビルド設定ファイル(conf.py) — Sphinx 1.5.6 ドキュメント
例として今回の僕の場合はlatexに出力した時に本っぽいスタイルになって欲しかったのでjsbookドキュメントクラスに変更した．
latex_docclass = {'mydocument': 'jsbook'}
8.出力
8.1.html出力
$ make html
プロジェクトのルートディレクトリで実行する．
8.2.pdf出力
$ make latexpdf
これもプロジェクトのルートディレクトリで実行する．
9.reSTの書き方
9.1.セクションの分け方
以下のように書く．
Section1
================
subsection
--------------
subsubsection
^^^^^^^^^^^^^^^^^^^
paragraph
"""""""""""""""""
詳細はここを見る．
reStructuredText Primer — Sphinx 1.8.0+ documentation
新しい記号でheaderをハイライトするごとにサブに移ってくらしい．統一さえされてればどんな記号でもいいらしいが，この例のをそのまま使うのがいいだろう．
ちなみにこんな感じでハイライトが短いと，
section
==
WARNINGが出るので，とりあえずめっちゃ長くしておけばいいと思う．
9.2.listを作る
mdと同じ感じでできる．
* hoge
* hogehoge
1. hoge
2. hogehoge
reStructuredText Primer — Sphinx 1.8.0+ documentation
9.2.図の挿入
.. image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right
.. figure:: ./_static/fig/hoge.png
:width: 300px
:align: center
:height: 200px
:alt: hoge
キャプション
figureの場合１行開けてインデントも揃えておくとそれがキャプションになる．
キャプションはfigureにはあるがimageにはない．
パスの指定はプロジェクトのルートディレクトリではなく.rstの置いてあるsourceから始める．
reStructuredText Directives #images
9.2.図をその場に表示
フローティングを止めてreSTで記述した箇所に画像をそのまま表示するには以下のようにconf.pyを修正する．
latex_elements = {
# Latex figure (float) alignment
#
'figure_align': 'H',
}
ここでtexのfigureを作る時の設定をいじっており，よくやるH(Here)の指定ですね．
9.3.tableの作成
基本的には
reStructuredText Directives
に書いてあるcsv table, list tableを使った方が楽．
特定のセルが結合したtableを，csv table, list tableでは作れなさそうだったので，以下の頑張って作るやり方でやった．
+---------------------------+-------------------------+
| a | あ |
| +-------------------------+
| | かきくけこ |
+---------------------------+-------------------------+
問題点としては，この方法だと，日本語を使った時にバイト数の違いからめっちゃずれてWARNING: Malformed table.が出まくる．
うまく調整してやればいいのだが，毎回texのコンパイルして微調整してってやると時間を食う．
今回は，速攻で完了するhtml出力を先にしてWarningが出ないようにtableのフォーマットを直すようにした．（全然根本的な解決にはなってない）
9.4.code block
.. code-block:: python
def hoge():
pass
コードサンプルの表示 — Sphinx 1.5.6 ドキュメント
9.5.クロスリファレンス
同じドキュメント内のheadingのリンクを貼ったりする．
:ref:`my-reference-label`
インラインマークアップ — Sphinx 1.5.6 ドキュメント
9.6.texの改ページ
texのコマンドをreST内に記述するようにしてできる．
.. raw:: latex
\clearpage
ちなみにhtmlを生成する時には何も変化しないので気にせず使って良い．
10.参考になるリンク
reST
4. Sphinxでの文章の書き方(reStructuredText) — study sphinx 1 documentation
latex
Sphinxを使うときに便利なLaTeXコマンド - Qiita
Re: SphinxのLaTeXのフォーマットをいじる - Hack like a rolling stone
Sphinx + TeX + PDF with jsbook - 検討!目論見委員会Z
11.備考
タイトルページのdateを消したいと思ったが，conf.pyのpreambleでdateを空欄にしても，
latex_elements = {
...
'preamble': '''
\date{}
''',
...
出力されたtexを見ると，その後どこからともなく今日の日付が挿入されていて消せない．．．
\setcounter{tocdepth}{2}
\date{}
\title{MyDocument}
\date{2018年05月22日}
今回は出力後にtexファイルを編集してもう一回以下のようにしてpdfを出力した。
$ platex MyDocument.tex
$ dvipdfmx MyDocument.dvi
これは面倒なので何かいい方法はないだろうか．．．