個人的なSphinx 利用術メモ

この記事では

　Sphinx を普段から使用している者が個人的に使えそうな書き方、および観点を記述します。PC関連のユーザマニュアルの書く目線の記述が多めです。

Sphinx 概要を三行で

　Sphinx は構造化した文章作成が得意なドキュメントビルダーです。 reStructuredText という形式のテキストファイルから、 make html または make latexpdf などのコマンド一つ実行することで、読みやすい html や pdf を簡単に作ることができます。

よく使う書き方

　Sphinx ではApiドキュメントなど Code が途中で入った文章、キャプチャ画像が多いマニュアルは構造的な文章は向いています。故に、繰り返す部分を予め定義しておいて使いまわす、など工夫をすると書きやすいし読みやすいです。以下、個人的に使う書き方をいくつか紹介します。

.rst のセクションのパターンを決めておく

　後で混乱を防ぐためセクションの記号パターンを決めるようにしています。こうすることで、例えば原稿執筆中に文章のどこの構造にあたる部分を書いているんだな、とわかり易くなります。Sphinx本家 によると

通常は、文字の種類と見出しのレベルは関係ないため、どの文字でも使用することができます。使用していない種類のアンダーラインが出てくると、見出しのレベルが一段変わる、というルールになっています。

とあるので、ルールを決めなくてもいいのでしょうけど、予めこうするときちんと定義してあったほうが書きやすいです。私は以下のように定義しています。

section-examples.rst

================================
大タイトル ([d+]. 単位)
================================
　第1章は、...

サブタイトル ([d+].[d+] 単位)
====================================
　ここでは、...について紹介します

サブサブタイトル ([d+].[d+].[d+] 単位)
------------------------------------------
　ここでは、前節の○○について詳細に...

サブサブサブタイトル ([d+].[d+].[d+] 単位)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
　1.2.3.4 など 4節にもまたがるような文章はあまり書かないようにしています

定義ファイルを作成してよく使う構文を使いまわす

　source ディレクトリの下に def.txt という定義ファイルを作成しておきます。そこで、画像の定義や、よく使うhtml の改行（見た目の関係でどうしても入れたほうが見やすいことがある）の定義など予め書いておきます。その上で、.rst の中で使うときがあったらそれを呼び出す、という風にしています。

def.txt

.. |img_success| image:: img/success.png

.. |html_pagebreak| raw:: html

   <div style="page-break-after:always" />

.. |html_break| raw:: html
   
   <br />

　本文のファイル中で定義ファイルの構文呼び出すときは、 .rst ファイルの先頭に、 .. include:: def.txt と記述し、呼び出す場所で |html_break| という感じで呼び出します。

include.rst

.. include:: def.txt

　本文内容 ...

以下の画像のようになれば成功です。

|img_success|

|html_break|

メニューセレクションの書き方

　マニュアルでよくある、 ファイル >> 基本設定 >> キーボードショートカット の様な書き方です。そのときは menuselection を使います。

menuselection.rst

:menuselection:`ファイル --> 設定`

と記述します。htmlやpdf など良い感じ強調されます。

「○○ボタンを押してください」というときの書き方

　ユーザマニュアルなどでよくある「○○ボタンを押してください。」を書く場合には、「○○」ボタンなどGUI に表示される部分を　guilabel を使って記述すると、よい感じに目立たせてくれます。ボタンのGUIにはこれを使うという取り決めにしておくと文章全体の統一感が出ます。

guilabel.rst

:guilabel:`パスワード変更` をクリックします。...

という形式で記述します。

Webページ参照 リンク

　Web ページのリンクは

html.rst

　詳しくは、 `こちら <https://www.example.com/>`_ をご覧ください

と記述すればOKです。上の記述どおり ` (バッククォート記号) と (スペース記号) と _ (アンダーバー記号) が入る位置に注意します。

アンカーリンク貼り付け

　アンカーリンクは、以下のように記述します。

html.rst

.. _設定ファイル:

   |conf_1|

～　中略　～

.. 呼び出すとき

　:ref:`設定ファイル <設定ファイル>` の画像を参考にして...

　上のように書くと、 .. _設定ファイル: で書いた場所（上の例では、設定ファイルの参考が記述されている箇所）に、 :ref:`設定ファイル <設定ファイル>` がアンカーリンクとなってくれます。pdf 閲覧ソフト上でもクリックしたら飛んでくれますのでとてもgood です。

Code を記述する

　Code を書く場合、シンタックスハイライトが出てくれるととても見やすいですよね。 そのためには .. code-block:: python と書けばpython のコードとして解釈されます。 :: の直後の部分を エイリアス と呼びます。

code_block.rst

.. code-block:: python
    :caption: unicode_or_str.py

    u1 = u"これはユニコード型文字列です" #  Unicode型
    s1 = "これはふつうの文字列です" # str型

    type(u1)
    # <type 'unicode'>
    type(s1)
    # <type 'str'> 

　例えば、javascript 書きたいときは 上の .. code-block:: ?? の部分に js? javascript? 何を書けばよいのか思い、調べてみました。以下はPython のプログラミングが必要です。

　Sphinx では文字解析には Pygments というライブラリを使うそうです。pip freeze を実行するとインストールされているか確かめられます。

print_all_lexers.py

from pygments.lexers import get_all_lexers
lexers = get_all_lexers()
for lexer in lexers:
        print lexer

　上を実行すると、出力にサポートされる言語の一覧が表示されます。注目すべきエイリアスの部分は、最初から二番目のタプルです。javascript だと以下

('JavaScript', ('js', 'javascript'), ('*.js',), ('application/javascript', 'application/x-javascript', 'text/x-javascript', 'text/javascript'))

('js', 'javascript')とあるので、javascript は js でも javascript でもいいと、いうことでした。他の言語も是非調べてみてください。

追記

　いくつか書き方を追記します。2019/10/30

脚注

　脚注の書き方は以下のようになります。

foot_note.rst

　脚注 [#f1]_ はこんな感じです。

.. [#f1] 脚注とは、印刷における組版用語で、そのページ内、または見開きの前後2ページ分の後のページの本文の下部に印刷された注釈を指す。（Wikipediaより）

上の[#f1] という部分が参照元で、下が脚注として表示されます。 #f1 となる部分ですが、# + 英数字 で文章として一意であればよいらしいので私は項目毎に名前をつけています。ちなみに [#] と記載すると、 自動でナンバリングしてくれます。これと書き方が似ているのが、次の 引用 です。

引用

　引用する場合は、以下のように記述します。

citation.rst

　Wikipedia から以下の文章を引用します。 [CT1]_ 

.. [CT1] 引用とは広義には、自己のオリジナル作品のなかで他人の著作を副次的に紹介する行為、先人の芸術作品やその要素を副次的に自己の作品に取り入れること。報道や批評、研究などの目的で、自らの著作物に他の著作物の一部を採録したり、ポストモダン建築で過去の様式を取り込んだりすることを指す。狭義には、各国の著作権法の引用の要件を満たして行われる合法な無断転載等のこと。

以上