Date: 2017-03-18
Tags: sphinx

sphinx-extcode を作りました at Sphinx+翻訳 hack-a-thon 2017.03 #sphinxjp

Sphinx+翻訳 hack-a-thon 2017.03 に参加しました。

参加者:

@tk0miya (会長), @jbking (副会長), @yousken900 (副会長), @shimizukawa (会計), @pashango2 @nskgch @usaturn, @kashew_nuts

参加者が8人もいて、ここ数年で最多の参加人数だった気がします。

みんながやったこと

../../../../_images/todo3.jpg

  • @tk0miya: Sphinxのメンテ。画像を各ビルダーで扱えるように変換する仕組みを作っている。あとSphinx用にPythonのパーサーを書いてた

  • @jbking: Blogツールのアップデート

  • @yousken900: Sphinxの入門をしている。Sphinx-usres.jpの入門記事を読んでいろいろ書いてみた

  • @pashango2: Sphinxの新規プロジェクトを始められるGUIツールをQtで作っていた。Sphinxがconf.pyのテンプレートをべた書きで持っていて、外部ツールが再利用するのはつらい。プロジェクトのソースディレクトリもconf.pyになくてMakefileにしかないのでつらい。

  • @nskgch: Sphinx-1.6向け翻訳を進めた

  • @kashew_nuts: Tinkererをためしてみた(Sphinx+翻訳 Hack-a-thon 2017.3に参加しました #sphinxjp)

  • @usaturn: Sphinxのissueをトリアージする

  • @shimizukawa: Sphinxの本のリファレンスページを更新している。extcodeという拡張を最新のSphinxで動作するように修正していた

自分がやったこと

Sphinxをはじめよう の改訂作業をやってました（ Sphinx本の執筆 @ ルノアール市ヶ谷外堀通り店 に引き続き）。

この執筆用にsphinx-extcodeという拡張を作りました。

../../../../_images/sphinx-extcode.png

sphinx-extcodeの出力例

いくつかの出力例を https://shimizukawa.github.io/sphinx-extcode/ で見れます。

作った目的

たくさんのサンプルコードをreSTで書いて、その出力結果を並記するというのを繰り返していますが、コードサンプル用とレンダリングイメージ用とで2回書くのが面倒です。 こんな感じです:

.. code-block:: rst

   単語を * で囲うと *強調* になります。

   ** は **より強い強調** に使います。

出力例

   単語を * で囲うと *強調* になります。

   ** は **より強い強調** に使います。

コピペは必ずミスに繋がるので、サンプルを sample.txt という外部ファイルに書いて以下のようにする方法もあります:

.. literalinclude:: sample.txt
   :language: rst

出力例

   .. include:: sample.txt

これはこれで良いのですが、いちいち外部ファイルを用意する必要があります。 これを簡単に済ませようというのがsphinx-extcodeの目的です。 Sphinxをはじめよう を2013年に執筆したときに作ったんですが、原稿ソースと一緒に埋もれていたので、今回の改訂用にSphinx-1.5で動作するように修正したのが、今日の成果です。

残念ながら、パッケージ公開するほど安定していませんが、使ってみたい人はリポジトリから取得してみてください。 https://github.com/shimizukawa/sphinx-extcode