.. _Sphinx Tea Night 2017.07: https://sphinxjp.connpass.com/event/61387/ 自己紹介 ======== * shimizukawa: Sphinxのソースコードをメンテナンスしたりしてます。Sphinx-users.jpのイベントにはほぼ全部参加してます。2010年にSphinxを知ってから少しずつ関わってきた感じです。 * dtzx（たかはし）さん. 最近時間ができたので、以前ドキュメントを作るツールとして見掛けたSphinxの勉強会があったので、参加してみました。 * nskgch（さかぐちさん）: Sphinxイベントに参加しはじめて1年たってない新参者です。Sphinxドキュメントの飜訳をちょっとやったりしてます。仕事でドキュメントの構造化や日本語英語の一元管理なんかが必要で、Sphinxをそこに使っています。 話したこと =========== reStructuredTextってなんですか、Markdownじゃないんですか ------------------------------------------------------------- * SphinxはMarkdownでドキュメントを書けるって聞きました * Markdownでも書けるけど、標準ではreStructuredTextで書きます。 * reStructuredText? * Markdownは「マークアップはルールが多いから、アップせずにダウンしよう」ということで文法を可能な限りそぎ落としてます。代償として、表現力が落ちました。Markdownで表現できないことは、HTMLタグが使えるのでHTMLで書きます。 * reStructuredText (reST) は可能な限りreSTの文法で表現しようとしてるので、Markdownよりも表現力が高いです。代償として、記法が非常に多くて全部覚えるのはかなり難しいです。 :doc:`前回 <../sphinxjp-tea-night-201706/index>` も似たような話題が出てたのでそちらも参照すると良いかも。 reSTのサポート機能があるエディタってありますか ------------------------------------------------------- * reSTをサポートしたエディタ、例えば、補完やハイライト機能があるエディタってなにかありますか * わからない.. Vimとか？ * Vimだと一般の人に使ってもらえないので... * さすがにモードのあるエディタは無理ですよねー * ハイライト機能だけなら、色々なエディタが対応可能なんじゃないかなあ * ツールボタンで強調表示の記法を入れたりとかはプラグイン入れればできそう（あるかは知らない） * でも結局のところ、一般の人が欲しいエディタってWordなんですよね。記法のサポートじゃなくて、見た目そのまま編集出来るのが重要、っていう。 Sphinxで何書いてますか ------------------------------ みなさんドキュメント書くのにSphinxを使うんですか？ * 清水川の場合 * ちょっとしたメモも含めてほとんどreSTで書いてます * Githubは.rst拡張子や.md拡張子で記法に合わせてフォーマットしてくれるので、ソースコードに同梱するちょっとしたREADMEなんかも.rstにしてます * 最終的にまとめてそれっぽいドキュメントファイル(HTML等)にしたい場合、Sphinxのプロジェクトにそのファイルを放り込んで（組み込んで）ビルドすることもあります。 * それ以外にも、自分の個人blogはSphinxで書いてるし、本の翻訳やってるのもSphinxでやってますね。 * nskgch さんの場合 * 本業は開発者じゃなくリサーチャーなので、開発ドキュメントは書かないです * 調査をまとめるときに、英語と日本語を一元管理していく必要があって、Sphinxの飜訳支援機能が役立ってます Sphinxの飜訳支援機能は便利ですね ------------------------------------ * 飜訳支援機能がないとどうなるか * 原文のドキュメントを編集して、原文をコメントアウトして、下に訳文を付け足していく * 飜訳自体は問題なく出来るけど、原文が更新されたときに大変 * コメントアウトしてるので、原文の差分を突き合わせるのがまず大変 * 突き合わせしたあと、差分を確認して再度飜訳するのもちょいちょいめんどくさい * 三単現のsの有無しか差が無い場合なんかもぜんぶチェックしていなかければいけない * Sphinx i18n機能（といいます）があると楽 * Sphinxのドキュメント原文にある文章をパラグラフ単位で抜き出して.potファイルに書き出す機能 * .potに文章の対訳を書き加えて.poとして保存し、Sphinxドキュメントに再度食わせると、飜訳されたHTML等の出力が得られる * この.pot/.poファイルはgettextというデファクトスタンダートなフォーマット * このファイル形式に対応しているツールやサービス(transifex等)を使うことで多人数の飜訳がとても楽に行えるようになった * 原文の差分が発生したら、飜訳が一旦無効化されるので、そういうところだけ再度飜訳すれば良い。さらに飜訳メモリの支援があると、ちょっとした変更ならサクサク対応できるので仕事を速く終えられる。 * i18nを使わない場合もある * 英語の本などの飜訳では使わない * 本だと、訳注などを追加したり文章の前後を入れ替えたり、大幅に削除したり書き足したりがある * 原文と訳文のペアでしか管理出来ない仕組みでは、本の翻訳に向かない * なので、コメントアウトして訳文を書き足す方式が安定 * i18nはその昔、Google Summer of Code で開発されてSphinxに組み込まれました * 参加した学生(@lehmannro)が2ヶ月くらいで開発した（たぶん * Sphinx-1.0か1.1の頃(2010年)には動いてたけど、まだまだ実用的じゃなかった * 個人的に興味のあった清水川が修正パッチを送ったりして、1.2でだいぶ実用的になった * docs.python.jp のドキュメントはSphinx-1.2 からi18n機能を使って飜訳版を用意している * Sphinx-1.3 でだいぶ安定して使えるようになった * 機能的には十分ラインを超えているけれど... * 実装レベルで見ると、だいぶコードがやばい状態 * 色々な闇が満載なので、直したい... toctreeってなんですか --------------------------- * TOC-TREE で、Table Of Contents Tree の略です * Table Of Contents は日本語で「目次」ですねー。英語ではTOCって略されることが多いイメージ * 本は、本 -> 章 -> 節 -> ... のようにツリー状に構成されているので、そのツリーを繋ぐのがtoctreeの役割です。 やったこと =========== * 質問に答えて、このblog書いてました。今日のSphinx Tea Nightの様子です #sphinxjp (@ 喫茶室ルノアール 市ヶ谷駅前店 in 千代田区, 東京都) https://t.co/vH7dVzDZN4 pic.twitter.com/5900IPbY8V
— Takayuki Shimizukawa (@shimizukawa) 2017年7月11日