OpenStreetMapに対応したSphinxの拡張を書いてみた

はじめに

週末ちまちまとOverview — Sphinx 1.2.3 documentationの拡張を書いていた。

動機はドキュメントに地図を埋め込みたかったから。探してみたら先人はいるものですでにそのような拡張はあった。sphinxcontrib-googlemapsがそれ。

sphinxcontrib-googlemaps 0.1.0 : Python Package Index

あるのだが、次の点が不足していた。

• オフラインでも地図を参照したい
• ミリ秒表記も受け付けて欲しい
• マーカーとか矩形とか円とかもたくさん表示したい
• 埋め込んだドキュメントを配布したい

googlemapsを改造するのもありだけど、ドキュメントの配布の点でちょっとひっかかる。 というわけで、別案としてOpenStreetMapを採用してみるか、ということになった。

OpenStreetMap

leaflet.jsを使う

OSMではleaflet.jsを使うのが主流のようである。

Leaflet - a JavaScript library for mobile-friendly maps

ただ、ラベルまわりはちょっとそのままだといま一つ感があったので、

Leaflet/Leaflet.label · GitHub を使うことにした。こちらのほうがラベルの表示は好みというのがその理由。

sphinxcontrib-openstreetmap

というわけであれこれ試行錯誤しつつopensteetmapディレクティブを実装した。このディレクティブはこんな感じで使う。

.. openstreetmap:: Example Taiyaki in rectangle
   :id: taiyaki_in_rectangle
   :location: 35.7119,139.7983
   :zoom: 15

   "たいやき探索範囲", rectangle: 35.7185,139.7912,35.7065,139.8069
   "根津のたいやき", location: 35.720253,139.762573
   (以下略)

矩形を描画してみたりもできるようにした。こんな感じ。

駅から500mの円を描いたりもできる。こんな感じに。

オフライン対応については、だいたいこのくらいのタイルを事前に取得しておけばいいよね、くらいでやっているので力技感あるけどひとまず目的は達成できた気がしている。

kenhys/sphinxcontrib-openstreetmap · GitHub

まだ、記法とか固まってないし、あれこれ足りないものがある。 そこそこ使えるようになってきたら、いずれはsphinxcontribにもっていきたい。