Doxygen vs. Sphinx+Breathe

LinuxCon Japan 2016でLinux Kernelの文書でSphinxが使われていることをしった。 ソースコードのドキュメント化にはDoxygenがメジャーだったが,SphinxではBreatheという拡張機能を使うことで,Doxygenの結果をSphinxで取り込むことができる。 そこで,DpxygenとSphinx+Breatheのどちらがよいか考えてみた。 続きを読む
プログラミング markup
0
. @senopen
#linuxcon カーネルのドキュメント。 ・txtファイル:2000+ ・DocBook:カーネルの心臓の記述 ・Doxygen形式と似たのKerneldocコメント:55000個。 カーネル開発者がシステムを作った。 make htmldocs
. @senopen
#linuxcon 問題点が。 ・遅い ・brittle ・設定とmakeが難しい ・他のDocumentation/ディレクトリと統合がない。 最近変えた。 markdonwを導入。その後AsciiDocに切り替えた。
. @senopen
#linuxcon AscIiDoc 利点 ・汚いDocBookを回避 ・よりよい文書 欠点 ・パフォーマンス ・文書館のリンク ・Ruby依存
. @senopen
#linuxcon 何がやりたいか。DocBookはやめたい。 簡単なマークアップを使いたい(Markdonw,AsciiDoc,Sphinx)。 フォーマットされていない文書にもそのまま使いたい 東道された文書ツリーを作りたい。
. @senopen
#linuxcon それでSphinxに目をつけた。 ・コードの文書化に特化 ・世界的な利用 ・DocBookやLaTeXに頼らない。 で,Sphixを使うことで合意が取れた。 kerneldocコメントはいつも動作して,RST指示文を追加できる。
. @senopen
#linuxcon 拡張モジュールを作った .. kernel-doc:: file :export: :internal: :doc: doc-setion title :function: functions.. これだけでうまくいくようになった。
. @senopen
#linuxcon 今後の作業 DocBook文書を変換して,DocBookはやめる。 kernel-docユーティリティの再検討 plain-text文書の組み込み 表生成の改良 武藤さんのいうとおり,マークアップにとって表は鬼門か…
. @senopen
.@senopen 世界情勢考えるなら,やっぱSphixが一番なんかな。 AsciiDocはあまり使われていないし不十分か。DocBookは古臭くてやっぱだめか。 今後CSS組版を普及させることを考えると,やっぱSphinxも使えるようになっといたほうがいいか…
. @senopen
@senopen 貧弱で独自拡張が乱立しまくっているMarkDownに比べたら,Sphinxのほうがよっぽどましだもんな。
. @senopen
#linuxcon 2日目のセッションのカーネル文書の話で,AsciiDocからSphinxに移行した話があった。気になったので調べてた。rstは標準でCのAPIの機銃記法があるのがとても大きいと思う。 Sphinxドメイン - docs.sphinx-users.jp/domains.html#c…
. @senopen
個人的にはきちんとした文書を書くならXHTML5が一番だと思っていて,これをメインにやっている。 でも,コードの文書化とかなってくると,コメントに埋め込んだ文とか,結局変換が必要。軽量マークアップ使うしかないんかな。二度手間だけど,どちらでもできるようになっておく必要があるか…。
. @senopen
これAsciiDocなんだ。 やっぱりSphinxよりAsciiDocのほうがいいようにみえるけど…。ただ,AsciiDocを選ぶことは人柱の覚悟が必要。 Vulkan Style Guide - khronos.org/registry/vulka…
. @senopen
@senopen Sphinxを使うなら,PDF生成に結局またTeXに関わらないといけなくなる。TeXにはもう関わりたくない。けど,AsciiDocだと評判の悪いDocBook経由。 消耗したくない…
. @senopen
先週参加したLinuxConの参加報告を昨日会社に提出した。個人的に興味のあったカーネルドキュメントの話について,以下に組版が大事かSphinxについて書いていたら,上長に興味を持ってもらえたらしく,サンプルの掲示をお願いされた。チャンスかな。社内Wikiも数年誰も使っていないし
. @senopen
@senopen 組版の重要さというのがあまりわかっていないようだ。 SphinxよりかはAsciiDocのほうが好みなのだけど,ユーザーは多いし安定しているからな。Sphinxの力を借りさせていただくか。
. @senopen
会社でお願いしてこの本買ってもらおうかな。Sphinxについて知りたい。 Pythonプロフェッショナルプログラミング 第2版 株式会社ビープラウド amazon.co.jp/dp/B00XZTYMG6/… @amazonJPさんから
. @senopen
この本買った。最初はePubしかなくて残念だったのだけど,いつからかPDF版もでていた。 O'Reilly Japan - Sphinxをはじめよう oreilly.co.jp/books/97848731… @oreilly_japanさんから
. @senopen
次からはSphinxをはじめようを読んで勉強しよう。
. @senopen
2015/05/21 #PyPro2 の電子書籍が出ました! - Pythonプロフェッショナルプログラミング第2版 - 清水川Web - freia.jp/taka/blog/pyth…
. @senopen
Sphinxを使用しているプロジェクト — Sphinx 1.4.4 ドキュメント - docs.sphinx-users.jp/examples.html
. @senopen
RT @togetter_jp: C++向けドキュメンテーションツールの悩み覚書 - Togetterまとめ togetter.com/li/141233
. @senopen
Is Sphinx already suitable for C++ documentation? - Stack Overflow - stackoverflow.com/questions/1293…
. @senopen
GitHub - michaeljones/breathe: ReStructuredText and Sphinx bridge to Doxygen - github.com/michaeljones/b…
. @senopen
Sphinx FAQ — Sphinx 1.4.5 ドキュメント - sphinx-doc.org/ja/stable/faq.…
残りを読む(23)

コメント

コメントがまだありません。感想を最初に伝えてみませんか?

ログインして広告を非表示にする
ログインして広告を非表示にする