Date: 2017-11-28
Tags: sphinx, sphinxcon

SphinxCon JP 2017 に参加しました #sphinxjp

SphinxCon JP 2017 に参加しました。

イベント:

SphinxCon JP 2017

参加者:

38名前後

会場:

DeNA社（渋谷ヒカリエ）

時間:

19:30 - 22:00

../../../../_images/kanpai.jpg

DeNAさん提供のケータリングでカンパイ!

場つなぎ

  • Q1.

      1. Sphinxを使ったことのある方

      1. かなりいますね！

  • Q2.

      1. ヒカリエに初めて来た方

      1. けっこう居ますね！

  • Q3.

      1. 書籍関連の話を聞きたくて来た方

      1. けっこう居ますね！

1: Sphinxが支える翻訳ドキュメント

  • Pythonドキュメント の翻訳をしている

    • 23万ワード

    • 本にして 1577 ページ、重量にして5.7kg

    • 原文は日々変わっていく

    • 翻訳は追いかけるのが大変、何人かでがんばっている

  • 翻訳プロジェクトを始めるときに考えること

    • 原文と訳文が1対1で、構造が完全に一緒でよければSphinxが使える

    • 脚注訳注を入れたい、構造を変えたい、ならSphinxはあきらめよう

    • 単発型か継続型か。Pythonドキュメントは継続型

  • 翻訳を支える機能・サービス

  • Sphinx gettext

Q&A

  • Q: (@kmuto) potのメッセージはドキュメントの順番にならぶの？

    • A: （清水川）並ばないことがあります。同じメッセージが複数回でてくると初回のみカタログに出てくるし、あとで原文が追加されたらpotの末尾に追加されます

    • (kmuto) 前後を読みながら翻訳したいので、原文の通りに並んでてほしいなと思うんですよね

  • Q: （鹿野桂一郎）TransifexはSphinx専用ではないですよね？一般的なpotを扱えるサービスですよね

    • A: はい

    • Q: それをSphinxから使いやすいように清水川さんが作ってくれたということですね

    • A: はい

2. Sphinxで売り物の書籍を作ってみた

  • Goならわかるシステムプログラミング

    • 元はASCIIさんで連載していた

    • 著者はいま目の前でなにかモグモグ食べている @shibu_jp さん

    • Sphinxで原稿を書いてHTML化していた

    • 書籍化にあたり、Sphinxから出力してなんとかしたい

  • SphinxのTeXをハックした

    • 自分のLaTeXテンプレートを使いたい

    • 自作のLaTeXスタイルで見た目を変えたい

    • ブロック要素内の脚注を特別扱いしたくない

    • Sphinxは相互参照をHTMLのノリで作っちゃうのでやめたい

    • LaTeXの表は自動でキレイには組めない

  • 自分のLaTeXテンプレートを使いたい

    • Sphinxには _template/latex.tex_t を置くとテンプレートとして使ってくれる機能がある。やったね！

    • でも目次の位置は固定で変えられない！

    • 独自のdirectiveを作って、コントロールできるようにした

  • 自作のLaTeXスタイルで見た目を変えたい

    • Sphinxの code-block のデザインを変えたい

    • customenv ディレクティブで指定した環境で包むよにした

  • ブロック要素内の脚注を特別扱いしたくない

    • テーブル内に脚注を書くとテーブルの下にしか脚注を出せない

    • Sphinxでもけっこう苦労して対策している跡が見える

    • それでも特定のケースではうまくいかない

    • しょうがないので、通常の脚注にして自分のLaTeXマクロ(?)を使った

  • Sphinxは相互参照をHTMLのノリで作っちゃうのでやめたい

    • "第3章" を見てください、のように章番号だけ表示したい

    • :numdoc: を作った

    • :numdoc: と :doc: を並記しないといけないのは微妙だけど、まあしょうがない

    • ページで参照したい。どうしたらいいかな

    • しょうがないので :tex: ロールを作ってLaTeXを直接書き込んだ

  • LaTeXの表は自動でキレイには組めない

    • Sphinxではtabularyパッケージにやらせている

    • しかしLaTeX側に全て自動で良い感じにやらせるのは無理

    • tabularcolumns ディレクティブで個別指定できる！！ (by tk0miya)

  • まとめ

    • 困ったら日本語でツイートすればいい

    • ある程度リッチな紙の本を作るにはSphinxくらい充実してても手をかけないとイケない部分がたくさんある

    • ラムダノート社 がお手伝いするよ

3. Re:VIEWとSphinxと、時々、ボク

  • 軽量マークアップの傾向

    • Markdown -> Web

    • Re:VIEW -> 技術書籍

    • reStructuredText -> Web, PDF(not 組版)

  • 技術書籍を書きたい、Sphinxで書きたい!

    • sphinxcontrib-reviewbuilder を作った

    • 作ったのは2,3年前

    • pip install sphinxcontrib-reviewbuilder して

    • conf.py に書き足して

    • make review

    • できました

  • reviewbuilder を使って書かれた本

  • Re:VIEWからreSTへ

  • Big Mouth Data

    • 技術書典2で頒布

    • Re:VIEW -> reST -> Re:VIEW

    • 相互変換できるようになってきた

  • Re:VIEW と reST

    • Re:VIEW: 組版用コマンドが豊富

    • reST: 汎用的、拡張が容易

    • カバー範囲が異なっている感じ

    • 相互変換できるといってもカバー範囲が違うので、変換を繰り返したら元には戻らない

  • まとめ

    • Sphinxは拡張が豊富

    • 設計思想の違いがある。優劣ではない

    • Sphinxは拡張が PyPI にたくさんあるので色々さがしてみて

    • 拡張が無ければ自分で書けばいいじゃない！

感想

4. 社内のマニュアルをSphinxで作ってみた

  • 今日はドキュメントの技術的負債の話をします

    • 技術ドキュメントを残していく必要性がでてきた

    • 社内ではExcel方眼紙が跳梁跋扈している！

    • PCへのインストールは制限されている！

    • でもMacは管轄外だったのでSphinxいれちゃった

  • ドキュメントのメンテナンスは手間が掛かる

    • reSTやMarkdownは学習コストが掛かる

    • メンバーの作業コストが高くなりドキュメントが放置された

    • この負債を解消するために、ドキュメントが素のHTMLで書き直されつつある

  • まとめ

    • 独断でいれたツールはうまくいかないことが多い

    • 理解の難しい技術は、残されたメンバーが扱えなくなる

    • 中心メンバーが抜けた後の運用も考える必要が

    • 運用コストを考えると最終的にExcelが選択されることに..

    • 技術的負債とどう向き合うか

      • 技術レベルに合わない技術は爆死しやすい

      • 枯れすぎた技術を選んでも爆死する

      • 技術の学び方だけでなく、メンバーへの教え方も磨いていく必要がある

    • メンテナンスしやすいドキュメントの作り方

      • 何で作るかにこだわらず、誰でも編集出来ることが大事

      • 必要最低限のドキュメントだけ作る

      • 定期的にメンテナンスする機会を設ける

感想

  • メンテしやすいの部分、必要最低限、よりは必要十分な方を狙って行きたいね。

5. HTMLテンプレート再構築案

  • DeNA退職時に引き継ぎ資料をSphinxで書いた

    • make singlehtml で作ってHTMLをブラウザで全コピしてWordに貼ればOK

    • Word上でコードブロックもキレイに維持されて美味しい

    • medium.com の編集画面にも同じように貼れば良い感じになってくれる

  • SphinxのHTML5

    • HTML5リリースから9年遅れ

    • Sphinxは docutils の上で作られている

    • docutilsのHTML5対応が必要だった

  • Sphinx 2.0 に向けて

    • HTMLテンプレートの簡易化: 構造化よりコピーして使いやすい方がいい

    • 検索機能の向上: 検索インデックスの構造を変えて検索しやすく

    • Open Graph Protocol: Sphinxで標準対応したい

    • Offline Mode: Service Workerを使って

  • まとめ

    • 未来に向かっていこう

    • カスタマイズしやすいようにしよう

    • 共有しやすく

    • パフォーマンスよく

Q&A

  • Q: (jbking) HTMLテンプレートをカスタマイズしやすくしよう、について具体的なProposalってありますか？

    • A: (shibu_jp) 今のところないです。こまかく分割されてしまっているのを1つにまとめる事を考えています。後方互換性は気にしてるけど、新しい仕組みを選択できるようにしようと思ってます。

  • Q: (r_rudi) 検索の部分をなんとかしたいという話ですが、 Oktavia の開発は続けるんですか？

    • A: (shibu_jp) Oktavia はFM-Indexというのを使ってるんですが、検索エンジンとしてはそこまで良いものではない。ので、もういいんじゃないかなと思ってます。昔と違っていまは色々できるようになってきたので。

  • Q: (?): Sphinxは使ったことがなくて今日初めて色々聞いたんですが、さきほどのHTML5サポートはどうやって出力するんですか？

LT

おまけ