Help us understand the problem. What is going on with this article?

最小の労力でsphinxでpdfとhtmlを作る

More than 1 year has passed since last update.

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ドキュメントクラスに変更した.

conf.py
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の場合1行開けてインデントも揃えておくとそれがキャプションになる.
キャプションはfigureにはあるがimageにはない.

パスの指定はプロジェクトのルートディレクトリではなく.rstの置いてあるsourceから始める.

reStructuredText Directives #images

9.2.図をその場に表示

フローティングを止めてreSTで記述した箇所に画像をそのまま表示するには以下のようにconf.pyを修正する.

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で薄い本を書いてみた - 検討!目論見委員会Z

Sphinx + TeX + PDF with jsbook - 検討!目論見委員会Z

11.備考

タイトルページのdateを消したいと思ったが,conf.pyのpreambleでdateを空欄にしても,

conf.py
latex_elements = {
...
    'preamble': '''
    \date{}
    ''',
...

出力されたtexを見ると,その後どこからともなく今日の日付が挿入されていて消せない...

\setcounter{tocdepth}{2}

    \date{}

\title{MyDocument}
\date{2018年05月22日}

今回は出力後にtexファイルを編集してもう一回以下のようにしてpdfを出力した。

$ platex MyDocument.tex
$ dvipdfmx MyDocument.dvi

これは面倒なので何かいい方法はないだろうか...

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away