Sphinxで作るApple help book

目的

Sphinxは美しいドキュメントを簡単に作れるようにするマンドラインツールです。 これを転用して、アプリケーションのオンラインマニュアルを作成ができます。

Apple help bookはMacアプリケーションのオンラインマニュアルの形式です。このApple help bookはhtmlで表記する必要があります。

html直書きよりも簡易な表記が可能なドキュメント作成ツールSphinxでオンラインマニュアルを作成すると、ほんのりラクが出来る気がします。

Sphinxの出力形式にApple help book形式が2015年に追加されたましたので、少しだけ調べてみました。

作成手法

最小限の手間で既存のCocoaアプリケーションに、Sphinxで作成したオンラインヘルプを追加する方法を示す。流れは以下の5つの手順。

  1. Sphinx-quick-start

  2. configファイルの変更

  3. XCodeにスクリプトフェーズの追加

  4. apple help book fileをResorceとして追加

  5. 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ファイルを呼び出すために追加します。

../../../_images/appleHelpBook_script.png

追加したコードを以下に示します。

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"に追加します。

../../../_images/appleHelpBook_copy.png

これで、XCode上でビルドすると、アプリケーションバンドルに含まれるようになります。

info.plistの変更

最後に、info.plistに以下の2項目を追加して、アプリケーションにバンドル内のApple help bookを認識させます。

info.plistに追加する項目

キー

値

説明

CFBundleHelpBookName

com.mindto01s.HalloWorld.help

conf.pyで設定したapplehelp_bundle_idの値

CFBundleHelpBookFolder

HalloWorld.help

AppleHelpBookのフォルダ名
../../../_images/appleHelpBook_infoPlist.png

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

../../../_images/appleHelpBook_HelpViewer.png

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自体の解説はこちらを参考にしてください。

https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_concepts/apple_help_concepts.html

Apple Help Bookの構造自体はこちらの解説の方がわかりやすかったです。

http://devzone.touchdude.com/step-step-create-apple-help-your-cocoa-xcode-application

Sphinxの設定ファイルの書き方は本家が一番わかりやすいです。

http://www.sphinx-doc.org/ja/stable/config.html

じゃあね。

Previous: 画面分割その2   Next: NSTableViewのUIを改良する、その1

Comments

comments powered by Disqus