Sphinxで作るApple help book¶
目的¶
Sphinxは美しいドキュメントを簡単に作れるようにするマンドラインツールです。 これを転用して、アプリケーションのオンラインマニュアルを作成ができます。
Apple help bookはMacアプリケーションのオンラインマニュアルの形式です。このApple help bookはhtmlで表記する必要があります。
html直書きよりも簡易な表記が可能なドキュメント作成ツールSphinxでオンラインマニュアルを作成すると、ほんのりラクが出来る気がします。
Sphinxの出力形式にApple help book形式が2015年に追加されたましたので、少しだけ調べてみました。
作成手法¶
最小限の手間で既存のCocoaアプリケーションに、Sphinxで作成したオンラインヘルプを追加する方法を示す。流れは以下の5つの手順。
Sphinx-quick-start
configファイルの変更
XCodeにスクリプトフェーズの追加
apple help book fileをResorceとして追加
info.plistの変更
Sphinx-quick-start¶
以下のような既存のプロジェクトにSphinxのコードを追加します。
.
├── HalloWorld/
└── HalloWorld.xcodeproj
このディレクトリに、sphinxディレクトリを作成しそこを、カレントディレクトリにします。
.
├── HalloWorld/
├── sphinx/ <--- 今作った。
└── HalloWorld.xcodeproj
sphinx-quickstartコマンドでsphinxのテンプレートファイルを設置します。(私の環境では、2.7系のコマンドしかうまく動かなかったので、2.7系で使用しています)
$ sphinx-quickstart-2.7
Welcome to the Sphinx 1.4.3 quickstart utility.
.
.
.
> Root path for the documentation [.]:
> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: HalloWorld <—- 重要
> Author name(s): HalloWorld Author
> Project version: 1.0
> Project release [1.0]: 1.0
> Project language [en]: ja <—- 重要
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]: n <—- 重要
コマンドを実行すると、上記のように幾つか質問されます。重要点は3点だけです。
設定項目 |
説明 |
---|---|
Project name |
生成されるApple help bookのファイル名になります。 |
Project language |
ローカライズに使用されます。日本語ならばjaを使用します。 |
Create Windows command file? |
信仰心が試される箇所です。最後まで気を抜かずに、必ずnにしましょう。 |
コマンドの実行が終了すると、以下のようなディレクトリ構造になります。
.
├── HalloWorld/
├── HalloWorld.xcodeproj
└── sphinx
├── Makefile
├── build
└── source
configファイルの変更¶
sphinx/source/conf.pyを編集します。変更箇所は1箇所です。
# apple help book bundle のCFBundleIdentifierの値の設定。
applehelp_bundle_id = 'com.mindto01s.HalloWorld.help'
上記の1行を適当に追加してください。
この状態で、make applehelpを行うと、apple help fileが作成されます。 ただし、この状態では、アプリケーションバンドルにはコピーされませんし、ヘルプメニューから呼び出すこともできません。
XCodeにスクリプトフェーズの追加¶
XCodeでビルドした時に、自動でsphinxのmakeファイルを呼び出すために追加します。

追加したコードを以下に示します。
cd "./sphinx/"
PATH=${PATH}:/opt/local/bin
make applehelp
PATHに/opt/local/binを追加しているのは、私がMacPortsを使用しているため。他の方法でsphinxをインストールしてるならば別の場所のPATHを書いてください。
この時点で、XCode上でsphinxもビルド可能になります。
apple help book fileをResorceとして追加¶
XCode上で一度ビルドすると、"./sphinx/build/applehelp/"に、"HalloWorld.help"というapple help bookバンドルができます。 これを"Copy Bundle Resources"に追加します。

これで、XCode上でビルドすると、アプリケーションバンドルに含まれるようになります。
info.plistの変更¶
最後に、info.plistに以下の2項目を追加して、アプリケーションにバンドル内のApple help bookを認識させます。
キー |
値 |
説明 |
---|---|---|
CFBundleHelpBookName |
com.mindto01s.HalloWorld.help |
conf.pyで設定したapplehelp_bundle_idの値 |
CFBundleHelpBookFolder |
HalloWorld.help |
AppleHelpBookのフォルダ名 |

これで、アプリ実行後に、Helpメニューから"HalloWorld Help"を選ぶと以下のページが表示される。

Apple help book作成に関連するSphixの設定¶
Sphinxのoption項目で、Apple help bookに関連する項目の一覧です。
apple help book bundle用info.plsitの設定¶
- applehelp_bundle_name
Apple Help Bookのベース名です。デフォルトでproject名が使用される。
- applehelp_bundle_id
Apple Help BookのバンドルID(必須)。CFBundleIdentifierに反映される。
- applehelp_dev_region
Apple Help BookのCFBundleDevelopmentRegionに反映される。デフォルトで'en-us'
- applehelp_bundle_version
Apple Help Bookのバージョン文字列。デフォルトで1。CFBundleVersionに反映される。
多分、applehelp_bundle_id以外は設定しないで良いハズ。
その他の設定¶
- applehelp_disable_external_tools
この値がTrueだと、indexerやcodesignなどのコマンドラインツールを呼び出しません。つまり、MacOSX以外でビルドのテストを使用するときに使います。デフォルトで、false。
- applehelp_locale
バンドルのResourceフォルダーの中のロケールフォルダー(*.lproj)の生成に使われます。ここが、enならば、en.lprojを生成し、jpnならば、jp.lprojを生成します。デフォルトでlanguageの値。
- applehelp_icon
Apple Help Book用の16x16ピクセルのアイコンのファイル名。Apple Helpのリスト表示などの使われます。
必須でないけと設定してiconを作成しないとみっともないので、applehelp_iconは設定した方が良い。その他は設定は不要と思います。
出力されるhtmlファイルの設定¶
- applehelp_title
ヘルプファイルのタイトルの設定。デフォルトでは '<project> Help'です。 info.plistのHPDBookTitleの変更と、html中の<title>タグの変更。
- apple help bookの出力は、既存のhtml出力のビルダーから継承されているので、html関連のoptionを変更すると変更できます。
このapplehelp_title項目は設定しなくても良いと思います。
indexer用の設定¶
ヘルプファイルのindexを作成するためのコマンドラインツール用のoptionです。多分使わない。
- applehelp_indexer_path
hiutilコマンドへのパスの変更。変更する必要なし。
- applehelp_index_anchors
コード上からAppleHelpBookのページを呼び出すための、アンカー用indexを作成するか否か。Trueにする。アンカーの表記方法は知らない。
- applehelp_min_term_length
hiutilに渡すminmum term lengthの引数。an とかtheとかをindexに含めないようにするためのもの。変更の必要はないだろう。
- applehelp_stopwords
hiutilに渡すstop wordの引数。’about’や’then’などの単語をindexに含めないように、あらかじめstopWordとして登録しておいた単語を指定するためのもの。普通は変更する必要なし。デフォルトの登録内容でOK.
codesignの設定¶
apple help book バンドルに署名する必要があるときに使用するらしい。使うことがあるとは思えない。
- applehelp_codesign_identity
設定されている場合は、この値に設定されているidentityでコードサインされる。デフォルトでは、環境変数CODE_SIGN_IDENTITYに使われている値を使用する。
- applehelp_codesign_flags
設定されている場合は、この値のオプションをcodesignコマンドのオプションとして使用する。デフォルトでは環境変数OTHER_CODE_SIGN_FLAGSに使われている値を使用する。
- applehelp_codesign_path
コマンドcodesignへのパスを変更するためにあるらしいが、使うことはないハズ。
リモートアクセス系の出力のオプション¶
Apple Help Bookはネット経由でダウンロード出来たり、知識ベース(サポート掲示板を格好良くいう言葉らしい)へアクセスできるらしいが、使ったことはない。
- applehelp_kb_product
ナレッジベースへのURLの基本部分。デフォルトでは、'<project>-<release>'.
- applehelp_kb_url
知識ベースへのURL
- applehelp_remote_url
リモートコンテンツへのURL
多分、これからも使わないと思います。
参考資料とソースコード¶
プロジェクトファイルはここに置いてきます。( HalloWorld.zip
)
- 使っている人はここの人ぐらいかも。
https://alastairs-place.net/blog/2015/01/14/apple-help-in-2015/
- Apple Help Book自体の解説はこちらを参考にしてください。
- Apple Help Bookの構造自体はこちらの解説の方がわかりやすかったです。
http://devzone.touchdude.com/step-step-create-apple-help-your-cocoa-xcode-application
- Sphinxの設定ファイルの書き方は本家が一番わかりやすいです。
じゃあね。
Comments
comments powered by Disqus