はじめに

清水川貴之です。

2015年6月5日（金⁠）⁠～7日（日）にかけて、台北でPyCon APAC 2015が行われました。PyCon APAC はAPAC（アジア太平洋）地域の国で年ごとに行われるPythonのカンファレンスです。2010年からシンガポールで開催され、2013年には日本で、昨年と今年は台湾で開催されました。筆者はこのイベントで、Sphinxの機能を紹介する2つの発表を行ってきました。

Sphinxは、reStructuredText記法のテキストやPythonソースコードから、HTMLやPDFなどのさまざまな形式のドキュメントを出力するドキュメンテーションツールです。Python標準ライブラリのドキュメント作成のために作られたツールで、PythonライブラリであればSphinxでドキュメントを書くのが一般的、というくらい多くのPython関連ツール、ライブラリで利用されています。今回の発表は、Sphinxが持つ多くの機能のうち、よく話題に挙がる2つの機能の導入による効果を紹介するものです。

筆者は今年、3ヵ国以上の海外カンファレンスでSphinxに関するプレゼンテーションを行う、という目標を立てています（筆者のblog⁠）⁠。各地のカンファレンスで、多くのソフトウェア技術者たちと交流し、Sphinxを紹介したり、意見交換を通してSphinxの今後の機能向上に役立てるのが目的です。PyCon APAC 2015は、その中の1つ目のカンファレンスです。スピーカー募集に2つのプレゼンテーションを応募したところ、なんと今回、その両方を発表する機会を持たせてもらいました。

また、カンファレンス2日目の夜には夜市（Night Party）という企画がありました。この企画は、カンファレンス参加者は誰でも参加出来るパーティー兼コミュニティーブースという構成です。このブース募集にも応募し、Sphinxブース展示をさせてもらいました。

本記事では、PyCon APAC 2015での発表とブース展示の様子について、スピーカーの立場から紹介したいと思います。一般参加レポートは後日公開予定ですので、そちらをご参照ください。日本から初めて海外のカンファレンスに参加した芝田将さんが、カンファレンス全体の様子や各セッションの内容、日本からの移動手段といった、参加者の視点でのレポートをお届けする予定です。

なお、Sphinxの機能についてはSphinxの公式ドキュメント（日本語）やSphinx-users.jpサイトで紹介しています。また、Software Design 2015年4月号から、「⁠Sphinxで始めるドキュメント作成術」という連載記事を掲載していますので、こちらもご参照ください。

スピーカー懇親会：Speaker Night

カンファレンスの前日、6月4日（木）19:00から、スピーカーを招待して懇親会が行われました。筆者もスピーカーの一人として参加しました。日本からの参加者は筆者のほかに、PyCon JP 2015座長の鈴木たかのりさんが出席しました。

懇親会が開催された青葉新樂園はビュッフェスタイルのレストランで、日本からの観光客がよく訪れる青葉の系列店です。参加したスピーカーやカンファレンススタッフはビュッフェの台湾料理を頂きながら、それぞれ自由に雑談を楽しんでいました。

この懇親会で良かったと思うことは、カンファレンスのスタッフの多くと直接会えたことでした。スピーカーの応募をしてからこの日までの2ヵ月間、プログラムの日程調整、チケット購入、スプリント申し込み、会場敷地内の宿の手配、夜市ブースの申し込み、等々、多くのスタッフとメールでやりとりをしてきました。実際にカンファレンスが始まってからもスタッフとのやりとりは続きますが、こういった懇親会でお互いに顔を合わせて挨拶し会話することで、緊張をほぐす効果があったと思います。実際、翌日以降、会場で顔を合わせるとお互いに「やあ」という感じで声を掛けやすく、色々な相談や質問などもスムーズにできました。

この懇親会には、多くの台湾のスピーカー、海外からのスピーカー、APAC地域のPyCon代表、カンファレンスに招待されたキーノートスピーカー、そしてPyCon APACのスタッフといったメンバーが揃っていました。この機会を利用して他のスピーカーに話をする人、自国のPyConにスピーカーとしての参加を呼びかける人などがいました。

懇親会は21時過ぎに解散となり、筆者はカンファレンス会場のあるアカデミア・シニカ敷地内の宿泊先へと移動しました。この宿泊先に5泊したのですが、カンファレンス会場のすぐ近くにあるため、期間中は会場との行き来がとても便利でした。

1つめの発表：Sphinxによる貢献しやすい翻訳プロセス

カンファレンス2日目、6月6日（土）11:50から1つめの発表を行いました。

• タイトル：Easy contributable internationalization process with Sphinx
• スライド：

この発表で伝えたいポイントは3つあります。

1. ドキュメンテーションツールSphinxの概要を紹介すること
2. Sphinxにはドキュメントを翻訳するサポート機能があること
3. 翻訳ボランティアがOSSプロジェクトに参加しやすい仕組みを提供できること

Sphinxは、reStructuredText記法のテキストやPythonソースコードから、HTMLやPDFなどのさまざまな形式のドキュメントを出力できます。その出力形式の一つとして、翻訳しやすいgettext形式の翻訳カタログファイルを作成できます。また、翻訳カタログを使ったドキュメントの多言語化にも対応しています。翻訳者は、翻訳カタログを扱える好きなエディタやサービスでドキュメントを翻訳できます。これらをうまく組み合わせることで、翻訳してほしい開発者も、翻訳を通じてオープンソースプロジェクトに貢献したい翻訳者も、最小の手間で効果的に成果を出せます。

発表の持ち時間は40分で、発表後に残った8分で会場からの質問に答える時間を持ちました。そこでの質問は次のような内容です。

• Q1. 翻訳者は、どうやって翻訳元ドキュメントの更新を知るの？
  • A1. sphinx-intlを使うと、更新があればコンソールにupdateが表示され、対象の翻訳文字列は一旦空になります。
• Q2. sphinx-intlは翻訳済み文字列を一旦空にしてしまうということだけど、gettextのfuzzy機能に対応しないの？
  • A2. fuzzy機能に対応させる修正差分のPullRequestをもらってるので、早めに対応版をリリースしたいと思います。
• Q3. SphinxはMarkdown記法に対応しないの？
  • A3. 別の開発者が挑戦しているところですが、解決するべき課題もいくつかあります

筆者は英会話、特にリスニングが苦手なので質疑応答はとても緊張しました。2年前に同じ会場で開催されたカンファレンスでもSphinxの発表を行ったのですが、当時は何を聞かれたのか聞き取れず、回答できませんでした。今回は英語での質疑応答もなんとかこなすことができました。これは、今回のカンファレンスで最も嬉しかったことです。

夜市：Sphinxブース

カンファレンス2日目、6月6日（土）17:30からは夜市でSphinxのブース展示を行いました。

• PyCon APAC/Taiwan 2015 - Night Party

台湾では夜市（ナイトマーケット）と呼ばれる、縁日のような場所が何箇所もあります。PyCon APAC 2015 2日目の夜には、この夜市を模したパーティーが開催されました。PyCon APACの夜市は、カンファレンスの一部として参加費に含まれていて、誰でも参加できます。ビュッフェスタイルの食事があり、バンド演奏などの出し物もありました。この夜市に、筆者が出店したSphinxブースを含む15のコミュニティーブースが出店しました。

夜市は17:30からでしたが、はじめの10分くらいブースに全く人が来ませんでした。しかし、それ以降はパーティーの食べ物をゲットした参加者が徐々にやってきて、その後は人波が途切れること無く、20:00までの2時間半、50人くらいの人にSphinxを紹介しました。

台湾の参加者たちは、こういったブースに積極的にやってきて話をしていたように思います。ブースにやってきた人でSphinxのことを知っている人はほとんどいませんでしたが、とても熱心に質問していました。

ブース展示で聞いたSphinxについての反応をいくつか紹介します。

• Sphinxを知ってる人は50人中3人くらい
• Sphinxで作られているPython公式ドキュメントは全員が読んだことがある
• Sphinxで使うreStructuredText記法を知ってる人は10人もいない
• Markdown記法も半分以上の人が知らない
• ほとんどの人はドキュメントを書いていない
• Sphinxを会社名だと思われた（BSDライセンスのオープンソースです）
• みんなドキュメントを簡単に作りたいと思っている
• ドキュメントを手軽に生成できるSphinxにみんな興味を持ってくれた

SphinxはreStructuredText記法のテキストファイルから、様々なフォーマットに変換してドキュメントを出力します。このSphinxの最も基本的な機能についての説明が不足していたこともあり、画像からテキスト生成するOCR機能があるのか、と思われたりもしました。次の機会には、reStructuredTextのような記法からドキュメントを生成する、という仕組みに初めて触れる人にも分かりやすいポスターも用意しようと思います。

ブースの準備に際して、ポスターの作成や貼り合わせなどでPyCon APACスタッフや、隣のブースのPyCon 韓国のチームに色々と助けてもらい、なんとかブースを整えられました。協力してくれたPyCon APACスタッフ、PyCon 韓国チームにはすごく感謝しています。今回はなんとかなりましたが、次からは事前に用意したほうがよさそうですね。

2つめの発表：Sphinx autodoc - APIドキュメントの自動生成

カンファレンス3日目、6月7日（日）14:20から2つめの発表を行いました。

• タイトル：Sphinx autodoc: automated API documentation

• スライド：

この発表では、Sphinxの自動ドキュメント機能を使うと、Pythonプログラムの充実したドキュメントを手軽に作れることを紹介しました。

Pythonには元々の機能として、関数やクラスのドキュメントを扱う機能（docstring）があります。Sphinxは、このdocstringと関数やクラスの定義から自動的にAPIドキュメントを生成できます。この発表では、Sphinxの自動ドキュメント機能、autodoc、autosummaryを利用したドキュメンテーションの方法について紹介しました。

docstringに関数の説明や利用例を記載したドキュメントを書くことによって、プログラムとドキュメントの位置が近くなり、更新忘れや機能とドキュメントのズレが起こりにくくなります。また、Sphinxの出力を見ることで、API利用者の視点で情報の不足が無いかなどがわかるため、docstringに何を書くべきかがわかり、ドキュメントを書くモチベーションにつながります。

この発表では、会場の雰囲気を和らげる効果を期待して、自己紹介のまえに「みんなの写真を撮っていい？」と呼びかけてスマートフォンで写真を撮ってみました。日本語での発表時にはなんどかやったことがありますが、英語発表では初めてやりました。日本でも海外でも、参加者の皆のノリがよく、今回も会場から「Sure!（いいよ！⁠）⁠」という声があがり、筆者の緊張もだいぶほぐれたと思います。

もう一つ、雰囲気を和らげる効果を期待した演出として、docstring知ってる？ と言って手を挙げてもらったりしました。この発表に参加してくれた70人くらいのうち約50人くらいがdocstringを知っていましたが、実際にdocstringを使ってAPIドキュメントを書いているのは8人ほどでした。このように手を挙げてもらう際のポイントは、おおまかにでも挙がった手の数をちゃんと数えることです。そうすることで、会場のみんなもどのくらいの人が知っているのかを共有でき、また、これから先公開される動画でこの発表を見る人にも雰囲気が伝わります。

発表の持ち時間40分のうち残り2分まで時間を使い、2分で会場からの質問に答える時間を持ちました。このときの質問はIPythonに関連する内容だったと思うのですが、聞き取ることが出来ず、うまく回答出来ませんでした。前のQ＆Aは答えられていただけに、とても残念でした。ですが、また英会話を練習して、次こそはちゃんと聞いて答えられるようにしよう、と決意を新たにしました。

発表の準備について

今回の発表に向けて準備したことについていくつか紹介します。

スライドはPowerPointで作成していて、発表者ノートの欄に全ての英語文章をあらかじめ書いておきました。3年ほど前から英語の練習をしていますが、アドリブでプレゼンテーションするのはまだ難しいです。そこで、話す内容を全て書いておき、発表練習ではこれをスラスラと読み上げるのを目標にしました。

Skype英会話のレッスンをときどき受けているのですが、話す内容とスライドを講師の先生に送って、自然な英語になるように指摘してもらったりしました。このおかげで、冒頭の挨拶だけはスラスラと話せたんじゃないかな、と思っています。冒頭以降については技術的な話が多かったこともあり、先生にうまく技術用語を伝えるのは難しい課題でした。しかしこれをきっかけに、知識を持っていない人にどうやって伝えたら理解しやすいのかを考え、スライドにも反映できたと思います。

今回、資料作りは1ヵ月前から始めていたのですが、英語のスライドということもあり、なかなか思うように進みませんでした。そのため、作りかけの資料で発表練習を何度か行いました。筆者の場合、Sphinxのイベントで参加者に聞いてもらったり、会社で同僚に集まってもらって練習しました。そういった練習でみんなに指摘してもらったことの反映や、わかりやすさの改善などの仕上げは思いの外時間がかかりました。そのため、3日目の発表まで、つまり、ほぼ最後までずっと資料を作っていました。

そんな状況でしたが、各発表の直前に1人で通しリハーサルを行ったのはとても役立ちました。話す際に強調したいところや、ペース配分などをつかむことができたので、実際の発表でも狙った通りに終えることができました。

ギリギリになって慌てないためにも、発表資料は2週間くらい前には仕上げておいて、完成資料での通し練習は10回くらいやったほうが良いですね。

次のPyConへ

今回は、2つの発表、ブース展示、とSphinxを紹介する多くの機会を持てました。この機会を通じて、多くの人にSphinxの良さを知ってもらい、ドキュメントを作ることのきっかけを提供できたんじゃないかと思います。

このカンファレンスで多くの人と英語で話をしました。と言っても、お互いに英語が第一言語ではなく、発音の問題もあり通じづらいこともありました。そういうときはノートPCに英単語を書いて会話したりしました。技術の根っこがおなじであれば、お互いに片言の英語でもなんとか意思疎通できる、ということを経験できました。また、積極的に英語で話しかけてくる参加者を見習っていこうと思います。

Sphinxについては、今回のカンファレンス参加を通じて、まだまだ認知度が低いことがわかりました。また、多くの人がドキュメントを手軽に生成したいと思っていることもわかりました。そこで、次のPyConに向けては、そういったニーズに合わせてスライドの内容を見直し、改善しようと思います。

次は、今週6月17日（水）から開催されるPyCon Singapore 2015に行ってきます。