サクサク読めて、アプリ限定の機能も多数!
トップへ戻る
大谷翔平
tk0miya.hatenablog.com
Today, I released Sphinx-2.4.0, now available on the Python package index at https://pypi.org/project/Sphinx/. It includes 18 new features and 23 bugfixes. For the full changelog, go to http://www.sphinx-doc.org/en/master/changes.html. In this article, I'd like to introduce you to new features of autodoc. Support type annotations for variables Until now, autodoc did not document type annotations f
本日、Sphinx-1.7.2 をリリースしました。いくつかのバグが修正されているので、試してみてください。 pypi.python.org さて、リリースするまですっかり忘れていましたが、本日 3月21日は Sphinx の誕生日です。しかも、なんと 10周年です。 Release 0.1.61611 (Mar 21, 2008) ================================ * First public release.github.com Sphinx と僕の (だいたい) 10年間 僕が Python を使いはじめた頃から、既に Sphinx はよく使われていたので、かなり古くからあるツールだと思っていたのですが、実は 僕の Python 暦(2010年ごろ)とそんなに変わらないのですね。実際、Python を使いはじめた頃に 0.6.6 を使ってみたり、1.0
いつぞやの記事で「Sphinx をはじめよう 第2版」を書いた話をしたのを覚えてらっしゃいますか?ちなみに、オライリーさんのページはこちらです。以前に紹介したときは、紙媒体はイベントなどのオフラインでの購入に限定されていたのですが、いまでは通販でも手に入るようです。 電子書籍も好評発売中ですので、興味がある方はぜひとも見ていただければ、と思います。 www.oreilly.co.jp さて、宣伝から話を戻しましょうか。 オライリーマニアのみなさんに於かれましては、オライリー・ジャパンさんの電子書籍の制作に Re:VIEW が深く関わっているのは既にご存知かと思います(参考:Community Blog - オライリー・ジャパンのePUBフォーマットを支える制作システム)。 この本の出版の際も、Sphinx で書かれた原稿を Re:VIEW に変更し、レビューや校正の段階では Re:VIEW
あけましておめでとうございます。今年も毎年恒例の抱負エントリからはじめましょう。 年末はひとりアドベントカレンダー的なことをやろうとしていたのですが、とっちらかって終わってしまっていますね。書き溜めてある記事はないのですが、まだネタはありそうなので、どこかで愚痴を形にできるとよいのですが…。 それはさておき、今回もさくさくと去年を振り返ってみましょう。 2017年の抱負 として挙げたのは ひきつづき Sphinx のメンテナ活動をする Sphinx 以外のネタにも手を出す なにか使えるツールをリリースする (少なくとも一本以上) 技術書を読み続ける。時間を取る。 家の片付け 健康生活 の6個でした。 まずはそれぞれについて振り返っていきます。 ひきつづき Sphinx のメンテナ活動をする:△ 今年は仕事と執筆、体調不良のおかげでいつものペースでコードが書けずにもやっとしていました。 コミ
せっかくの SphinxCon ですが、体調不良で欠場してる— Takeshi KOMIYA (@tk0miya) 2017年11月28日 38度の熱が出たので、楽しみにしていた SphinxCon JP 2017 を休むことになってしまいました。 おかげで、Sphinx の魔改造の話や HTML テンプレートへの提案など、興味深い発表を聞きそびれてしまったのは非常に残念です。 資料は公開されているので、それぞれ噛み締めながら何度か読み返そうと思っています。 さて、今回の SphinxCon では僕はトーク枠を持っていなかったのですが、実はイベントに合わせて作っていたものがあります。 LT でお披露目しようかと思っていたのですが、間に合わなかった上に風邪でダウンしてしまったので、代わりにここで紹介しようと思います。 作ったのは pycmark というパッケージです。 github.com
みなさん、Sphinx 使ってますか? Python や Linux カーネルのドキュメントでご存知の Sphinx の書籍、「Sphinxをはじめよう」が改訂されます。 今週末の #技術書典 で僕らが書いた #Sphinxをはじめよう の第二版が発売されます。しかも今回は紙媒体!(電子版もあるよ)。これからSphinxを触ってみようかなと思っている方におすすめです。細かな加筆をしているので、第一版をお持ちの方にもおすすめです。 #sphinxjp— Takeshi KOMIYA (@tk0miya) 2017年10月17日 #Sphinxをはじめよう の第二版は 1) Sphinx-1.6 に合わせて加筆 2) 基本のマークアップの説明をアップデート 3) みんな大好きmarkdownの説明をAppendixとして収録 4) 画像系のツール/サービスとの連携まわりの章を追加 とあれこれい
昨日は Markdown の 2016年を振り返りましたが、今日は Sphinx の 2016年を振り返りつつ、 2017年の目標を適当に挙げてみようと思います。 2つのメジャーリリースと 13のマイナーリリース 今年は 1.3.4 から 1.5.1 まで、合計で 15のリリースを行いました。 2014年が 1.2.1 から 1.2.3 までの 3リリース、2015年が 1.3 から 1.3.3 までの 4リリースだったとの比較すると、コンスタントに改善を続けられたと感じています。 もうひとりのメンテナである清水川氏と相談し、Sphinx ではリリースポリシーを刷新しました。 おおよそ 1ヶ月おきに 1回のバグフィックスリリース、6〜8ヶ月おきに 1回のメジャーリリースを行うつもりで進めています。 少し前の記事にある通り、メンテナのリソースも十分にあるというわけではないので、あくまで目標で
Markdown、あなたのすぐとなりに潜む問題 昨日は toc 拡張の話ついでに、現在の Sphinx と markdown を取り巻く環境について愚痴ったわけですが、Markdown 業界は 2016年のこの時期になっても、いまだに共通的な仕様が決まっていません。 2004年、John Gruber によって生み出された Markdown は、12歳を迎えた現在、さまざまな markdown 処理系を持っています。 そして、不幸にも実装によって markdown の処理はそれぞれ異なってしまっています。 これは Markdown の仕様が曖昧であることと、それぞれの処理系で文法の拡張を行っていることから来ています。 Markdown 処理系による違い Markdown の仕様が曖昧であることは、さまざまな混乱を生み出しました。 babelmark2 が示すように、同じマークアップであって
いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinx で markdown を使うことができます。 Software Design 2016年4月号 Markdownで始めるSphinx MarkdownでSphinxできるようになったので試してみた(前編) - 意識の高いLISPマシン Markdownで書けるSphinxの構築 - Qiita しかし、recommonmark を利用しても、ドキュメント構造(toctree)を記述するためには部分的に reStructredText を使う必要がありました。 .. toctree chapter1 chapter2 chapter3 これは、文法を拡張する仕組みを持たない markdown の (commonmark の)構造上、仕方がないのですが、せっかく markdown でドキュメントを書いてい
Twitter で流れてきた コードの半減期とテセウスの船 | 開発手法・プロジェクト管理 | POSTD を読んで、興味深かったのでさっそく Sphinx のコードでも実行してみました。 その結果がこちらです。 コードの増え方は時期によって波がありますが、やはり Sphinx もコードの量は右肩上がりに増えています。そして、古いコードは徐々に整理されて少なくなっています。 面白いのは、生き延びた古いコードはある程度安定しているためか、削除されることが少なくなってきている一方で、新しく追加されたコードは入れ替わりが激しい傾向が読み取れます。 Sphinx はまだコードの追加と削除が繰り返される、活発なプロジェクトだということがわかります。 モジュールごとの半減期 さて、せっかくの機会ですから、別の角度からも見てみましょう。 このグラフは Sphinx の主要モジュールの年代ごとのコード比率
年末カウントダウン Sphinx 連載、第3弾です。 一切下準備をせずに連載を始めたので、早くも息切れをしています。 だれかと約束をしたわけでもないのに急にアドベントカレンダー的なものを始めるのは、なんだか死に急いでいる気がしてきました。 今回は、今年から Sphinx の利用者に加わったある大型プロジェクトについて紹介しましょう。 そのプロジェクトとは、世界最大級の OSS のひとつである Linux カーネルです。 現在の Linux カーネルドキュメント 今年開催された LinuxCon Japan 2016 で Linux カーネルのドキュメントに Sphinx を使うという発表がありました。 Linus Torvalds氏が登壇、「約10週間のリリースサイクルは続く」 - クラウド Watch それから約 5ヶ月。現在はどうなっているのか見てみましょう。 Linux カーネルのド
クリスマスが過ぎてから始まる Sphinx アドベントカレンダーへようこそ (嘘) Sphinx 大型連載第二夜です。 タイトルにある通り、Sphinx のメンテナ活動をして一年が過ぎたので、その話をします。 OSS 開発者のひとつのサンプルケースとして、何かの参考になれば幸いです。 Sphinx のメンテナ活動をはじめました 去年の 12月から Sphinx のメンテナ活動をはじめました。 Python のリリースマネージャ活動が忙しかったからか原作者の Georg の活動が鈍り、 また、その後を継いだ清水川さんも忙しくて身動きが取れなくなっていたことから、 コミット権をもらっていたことだし、パートタイムで手伝うかと思ったことがきっかけでした。 以前からコミット権は持っていたものの、一切メンテナとしての活動をしていなかったので、 徐々にチケットが溜まっていく様子に後ろめたくなったのかもし
今年はアドベントカレンダーにも参加していないし、こたつに入ってだらだら過ごそうかと思っていたら、なんか書けと煽られました。年末ですね。 @tk0miya qiita の記事まだー?— Tetsuya Morimoto (@t2y) 2016年12月25日 何を書こうか思考をめぐらした結果、mypy を Sphinx に導入した話でも書くことにします。 mypy については @t2y の 紹介記事 、翻訳記事が非常に参考になりました。 ですので、この記事は @t2y へのアンサーソングです。 なお、「導入した話」と名付けてはみたものの、まだ 100% 対応したというわけではないので、試行錯誤の様子と愚痴を書き留めていきます。 Sphinx に type annotation をつけてみた Sphinx では現在、 master ブランチに対して type annotation がつけられてい
Sphinx ではラベル記法と :ref: 記法を使って、 ドキュメントの様々な位置にラベルを張り、それを参照することができます。 .. _target: section --------- セクションへの :ref:`参照 <target>` を作ります。 さて、このとき、ラベルを貼っているのがセクションタイトルなどの場合は :ref:`target` という書き方でキャプションをリンクタイトルにすることができます。 ラベルとキャプションを認識する Sphinx は次の順序でラベルを認識します。 reST ファイルのパース処理において、ラベル記法をパターンマッチで見つける (docutils.parsers.rst.states:Body#explicit_construct()) target ノードを生成する (docutils.parsers.rst.states:Body#mak
flake8 のドキュメントを読むと、 警告を抑止する NOQA コメントについて lines that contain a # noqa comment at the end will not issue warnings. (訳: 末尾に # noqa というコメントがある行は警告されません) と説明されています。 しかし、実際にはすべての警告を抑止できるわけではありません。 例えば、インデントのスペースの数を数える警告(E111)は NOQA コメントの効果がありません。 $ cat test.py name = 'Taro' if name: print 'Hello,', name # noqa else: print 'Hello world' # noqa $ flake8 test.py test.py:3:3: E111 indentation is not a mult
先々週に cacoo の拡張をつくってそのあとパッケージングもしたのですが、 それに味をしめて(?) UML 系のツールとして名高い astah 向けの拡張もつくってみました。 sphinxcontrib-astah です。 やっていることは超シンプルで、内部で astah-command.sh を呼び出して いるだけです。 この間 cacoo 向けの拡張をつくった時に気づいたのですが、 API やコマンド経由で画像を生成するツールで、 なおかつ画像のフォーマットが常に PNG や JPEG などのラスター形式のものについては、 sphinxcontrib-cacoo の実装がほぼそのまま使えるのではないかと思います。 astah 拡張を作るときは cacoo の API を呼び出している部分を astah-command.sh の呼び出しに置き換えるぐらいの作業で対応することができました
vim 素人の @tk0miya です。 いままで .vimrc が 1バイト(改行文字)しかないってバカにされていたんですが、ようやくその呪縛を解く時が来ました。 python のリントツールとしてよく使われている flake8 を編集時に実行しようと思っていろいろ調べました。 適当にぐぐってみると 3 つほど vim プラグインを見つけました。 vim-flake8 https://github.com/nvie/vim-flake8 flake8-vim https://github.com/vim-scripts/Flake8-vim khuno https://github.com/alfredodeza/khuno.vim それぞれ、2,3 分触った感触をまとめます。 vim-flake8 最初に見つけたやつです。 vim で python 開発するとき pyflakes +
今日、こんなツイートをみました。 @wataradio blockdiagシリーズか、cacooで作った図をpngで利用ですかねー #sphinxjp— Takayuki Shimizukawa (@shimizukawa) 2014, 8月 12 Cacoo で更新した図を Sphinx に貼り付けるにはローカルに保存する必要があります。 せっかく便利なサービスを使っているというのにこれはちょっと不便ですね。 というわけで、Cacoo 上の図を Sphinx に取り込むための拡張である sphinxcontrib_cacooimage を作ってみました。 gist18192f92226a9bfc2e6c この拡張をインストールすると cacoo-image, cacoo-figure という 2つのディレクティブが利用できるようになります。 それぞれ image, figure ディレク
docutils はある形式の文書を別の形式に変換するフレームワークです。 このフレームワークを利用して rst2html や rst2latex などが提供されています。 しかし、docutils が標準で対応している入力形式は reST 形式に限られているので、 実際には reST 変換用のライブラリとして捉えられていました。 markdown 黄金時代 docutils や Sphinx の周囲では reST を中心としてドキュメントが記述されていますが、 2014年現在、軽量マークアップ言語の主流の座は markdown であると言っても過言ではないでしょう。 flavor が乱立していたり、拡張性に乏しかったり、困ったら HTML で書き下してあったりと、 記述能力が十分とはいえない markdown ですが、github を初めてとして様々な場所で用いられています。 4月1日は
この間の Sphinx+翻訳 Hack-a-thon で話題に上がった件について調査してみた。 お題は以下のとおり。 元の文書は markdown で記述されている Sphinx を使って翻訳してみようと思っている 元の文書が更新された時に差分管理できるとよい その場で出た案はタイトルの通りで、 pandoc で reST 形式に変換して Sphinx を使って gettext 化して sphinx-intl を使って transifex にアップロードして transifex で翻訳をすると良さそう というもの。 gettext 化を挟むことで、翻訳しやすく、また原文の変化を追いかけやすいそうな。 というわけで、実際に試してみました。 環境を作る お題は redis-doc。 まずはワークスペースを作る。 $ mkdir redis-doc $ cd redis-doc $ git in
hg-diff-highlight を実装するにあたって、difflib.Differ クラスの実装を一部コピーしました。 Python のライブラリをコピーして自分のプロダクトに取り込むので、 どのように扱えばいいのかライセンス上問題ないか聞いて & 調べてみました。 Python の標準ライブラリの一部を改変して、自分のソフトウェアに取り込みたい場合、この部分のライセンスはどのように取り扱うと良いのでしょうか。また、copyright 表記などをどうすればよいのかどなたかご存じですか。(difflib を書き換えてます)— Takeshi KOMIYA (@tk0miya) 2013, 12月 18 Python は PSF LICENSE AGREEMENT という独自のライセンスを採用しています。 このライセンスは BSD 系っぽい気がする。ゆるい。 制限少なめ。自由多め。 という
ここしばらく python 2.5 に対応した python コードを書いていなかったので気にもとめませんでしたが、 diff-highlight を書くときに python 2.4, 2.5 対応でハマったことについてまとめます。 ちなみに diff-highlight を python 2.4, 2.5 に対応させたのは、 連携先である mercurial が python 2.4-2.7 をサポートしているので、それに合わせたためです。 ちなみに、タイトルに python2.4-3.3 とありますが、この記事では 3.0 と 3.1 は対象としていません。 python 2.4, 2.5 パッケージを手に入れる (Ubuntu) 私がテスト実行環境として使っている drone.io では ubuntu (おそらく 10.04)を使っていますが、 ubuntu の python2.4
Git の diff を美しく表示するために必要なたった 1 つの設定 #git にインスパイアされて作り始めた diff-highlight にあれこれ手を入れ、1.0.0 として正式リリースしました。 diff-highlight と git-contrib/diff-highlight の違い 差分の中で +/- の行数が一致していないときのハイライトの扱い git-contrib/diff-highlight での表示 +/- の行が一致していないとハイライトされません。 diff-highlight では、マッチする行を認識してハイライトします。 +/- の行数が一致しても、文字単位でのハイライトをしてくれないケースがある git-contrib/diff-highlight での表示 差分の 1行目同士を比較しているため、pager の行がハイライトされていません。 diff-
つい一昨日、Mercurial の diff を美しく表示するために必要なたった 1つの設定 という記事を書いたばかりですが、 diff-highlight の動作を見ているといくつか気になるところを見つけてしまいました。 diff-highlight のイケてないところ 差分の中で +/- の行数が一致していないと文字単位でのハイライトをしてくれない こんな感じです。 編集前後の行数が一致するときだけハイライトしてくれるようです。 diff-highlight のコードを読むとこんなコメント付きで、行数が一致しない時は早々に諦めています。 # If we have mismatched numbers of lines on each side, we could try to # be clever and match up similar lines. But for now we
先ほどの記事 でエスケープシーケンスまわりについて調べている時に、 「出力先がターミナル(tty)の場合」と「出力先がファイル、その他の場合」でエスケープシーケンスを出し分けする方法が気になりました。 たとえば、ls コマンドでは $ ls --color=auto と実行すると、ターミナルへの出力の場合にはエスケープシーケンスによって色付きで表示されますが、 $ ls --color=auto > foo や $ ls --color=auto | less のようにファイルや別コマンドへの入力にした場合にはエスケープシーケンスが出力されません。 これと同じ動作をシェルスクリプトで実現しようとした場合、test コマンドの -t を使います。 t 1 で標準出力がターミナルかどうかを調べることができます。 if [ -t 1 ]; then printf "^[[31mhello wor
僕は長らく vim を使っている(おそらく 14,5年)のですが、常にシンタックスハイライトをオフにして使っていました。 オフにしている理由は、特にメリットを感じなかったことと、もうひとつは編集時のハイライトの挙動です。 vim のハイライトは編集モードであってもリアルタイムに色が変わっていくため、 文字列を書き始めようとクオートをタイプした途端、自分のいる行より下がすべて文字列としてハイライトされます。 僕はこの動作がとても嫌いで、クオートを打った瞬間にぎょっとしてしまいます。 とはいえ、コードを俯瞰するときにシンタックスハイライトされていると見やすいと感じるようになってきたので、 このシンタックスハイライトの挙動とうまく付き合えないか、周囲の人に相談したりぐぐったりしてみました。 対策1: すぐクオートを閉じる 多くの人がこの挙動は自然なものだと感じているようで、慣れればいいと言われま
tmux 使えよって罵倒されそうですが、未だに screen を使っています。 ようやく vim のシンタックスハイライトを有効にして生活し始めたのですが、 開発に使っているさくら VPS に設定を反映したところ 16色モードで動いていると判断されているため jellybeans colorscheme が大変切ない見栄えになってしまいます。 ビジュアルモードで範囲選択しようとしても、バカには見えないモードで範囲選択しようとするので使い物になりません。 せめてカラーパレットが 4096色あれば、グラデーションやらなんやらでごまかせるんですけどねえ(違) とりあえずぐぐる → 反映 いくつかの記事を読んでみた感じだと screen を 256色対応でビルドしなおして、 .screenrc に attrcolor b ".I" defbce on termcapinfo xterm* 'Co#
今日はちょっと毛色の違う話をしてみようと思います。 blockdiag はこれまで 5つの図に対応しています。 ブロック図 シーケンス図 アクティビティ図 論理ネットワーク図 ラック構成図 blockdiag シリーズはひとつのツールでひとつの図をサポートしているので、 これまでいくつもの要望やアイディア、ネタをもらってきました。 完全にジョークのものを除いて、どれも面白そうだな、と思っているのですが なかなか時間が取れずに手を付けられずにいます。 今日はこの "もしかしたら作られているかもしれない blockdiag シリーズ" を 紹介してみたいと思います。 新しいツールを作るときに最初に考えること blockdiag シリーズのツールの要望をもらったときに、 なるべく考えるようにしていることがいくつかあります。 未知の blockdiag を紹介する前に、この「最初に考える事」を見て
一ヶ月ほど前から schema2rst をちょこちょことメンテナンスしています。 はじめは flake8 でコーディング規約のチェックをかけてみただけだったはずなのですが、 その流れであれこれいじっているうちに一ヶ月経ってしまいました。 まだドキュメントや実装が不足している部分があるので 0.9.0 というバージョンにしましたが、 前バージョン(0.1.0)のときから使っていたので、既に使ってもらえるレベルのものだと思います。 ということで、このエントリーでは schema2rst 0.9.0 の紹介をしたいと思います。 schema2rst ってなんなの? schema2rst とはスキーマ情報から rst (reStructuredText) 形式のドキュメントを生成するツールです。 いわゆるリバースエンジニアリングをしてくれます。 開発者向けのドキュメントとしてデータベース定義書や
次のページ
このページを最初にブックマークしてみませんか?
『Hack like a rolling stone』の新着エントリーを見る
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く