Doxygen vs. Sphinx+Breathe

LinuxCon Japan 2016でLinux Kernelの文書でSphinxが使われていることをしった。 ソースコードのドキュメント化にはDoxygenがメジャーだったが,SphinxではBreatheという拡張機能を使うことで,Doxygenの結果をSphinxで取り込むことができる。 そこで,DpxygenとSphinx+Breatheのどちらがよいか考えてみた。 続きを読む
0
. @senopen

#linuxcon カーネルのドキュメント。 ・txtファイル:2000+ ・DocBook:カーネルの心臓の記述 ・Doxygen形式と似たのKerneldocコメント:55000個。 カーネル開発者がシステムを作った。 make htmldocs

2016-07-14 11:20:04
. @senopen

#linuxcon 問題点が。 ・遅い ・brittle ・設定とmakeが難しい ・他のDocumentation/ディレクトリと統合がない。 最近変えた。 markdonwを導入。その後AsciiDocに切り替えた。

2016-07-14 11:25:18
. @senopen

#linuxcon AscIiDoc 利点 ・汚いDocBookを回避 ・よりよい文書 欠点 ・パフォーマンス ・文書館のリンク ・Ruby依存

2016-07-14 11:28:51
. @senopen

#linuxcon 何がやりたいか。DocBookはやめたい。 簡単なマークアップを使いたい(Markdonw,AsciiDoc,Sphinx)。 フォーマットされていない文書にもそのまま使いたい 東道された文書ツリーを作りたい。

2016-07-14 11:33:19
. @senopen

#linuxcon それでSphinxに目をつけた。 ・コードの文書化に特化 ・世界的な利用 ・DocBookやLaTeXに頼らない。 で,Sphixを使うことで合意が取れた。 kerneldocコメントはいつも動作して,RST指示文を追加できる。

2016-07-14 11:41:10
. @senopen

#linuxcon 拡張モジュールを作った .. kernel-doc:: file :export: :internal: :doc: doc-setion title :function: functions.. これだけでうまくいくようになった。

2016-07-14 11:42:01
. @senopen

#linuxcon 今後の作業 DocBook文書を変換して,DocBookはやめる。 kernel-docユーティリティの再検討 plain-text文書の組み込み 表生成の改良 武藤さんのいうとおり,マークアップにとって表は鬼門か…

2016-07-14 11:50:58
. @senopen

.@senopen 世界情勢考えるなら,やっぱSphixが一番なんかな。 AsciiDocはあまり使われていないし不十分か。DocBookは古臭くてやっぱだめか。 今後CSS組版を普及させることを考えると,やっぱSphinxも使えるようになっといたほうがいいか…

2016-07-14 12:00:40
. @senopen

@senopen 貧弱で独自拡張が乱立しまくっているMarkDownに比べたら,Sphinxのほうがよっぽどましだもんな。

2016-07-14 12:08:26
. @senopen

#linuxcon 2日目のセッションのカーネル文書の話で,AsciiDocからSphinxに移行した話があった。気になったので調べてた。rstは標準でCのAPIの機銃記法があるのがとても大きいと思う。 Sphinxドメイン - docs.sphinx-users.jp/domains.html#c…

2016-07-15 01:14:26
. @senopen

個人的にはきちんとした文書を書くならXHTML5が一番だと思っていて,これをメインにやっている。 でも,コードの文書化とかなってくると,コメントに埋め込んだ文とか,結局変換が必要。軽量マークアップ使うしかないんかな。二度手間だけど,どちらでもできるようになっておく必要があるか…。

2016-07-15 01:21:22
. @senopen

これAsciiDocなんだ。 やっぱりSphinxよりAsciiDocのほうがいいようにみえるけど…。ただ,AsciiDocを選ぶことは人柱の覚悟が必要。 Vulkan Style Guide - khronos.org/registry/vulka…

2016-07-15 01:25:07
. @senopen

@senopen Sphinxを使うなら,PDF生成に結局またTeXに関わらないといけなくなる。TeXにはもう関わりたくない。けど,AsciiDocだと評判の悪いDocBook経由。 消耗したくない…

2016-07-15 01:27:26
. @senopen

先週参加したLinuxConの参加報告を昨日会社に提出した。個人的に興味のあったカーネルドキュメントの話について,以下に組版が大事かSphinxについて書いていたら,上長に興味を持ってもらえたらしく,サンプルの掲示をお願いされた。チャンスかな。社内Wikiも数年誰も使っていないし

2016-07-20 21:41:22
. @senopen

@senopen 組版の重要さというのがあまりわかっていないようだ。 SphinxよりかはAsciiDocのほうが好みなのだけど,ユーザーは多いし安定しているからな。Sphinxの力を借りさせていただくか。

2016-07-20 21:42:39
. @senopen

会社でお願いしてこの本買ってもらおうかな。Sphinxについて知りたい。 Pythonプロフェッショナルプログラミング 第2版 株式会社ビープラウド amazon.co.jp/dp/B00XZTYMG6/… @amazonJPさんから

2016-07-24 18:18:57
. @senopen

この本買った。最初はePubしかなくて残念だったのだけど,いつからかPDF版もでていた。 O'Reilly Japan - Sphinxをはじめよう oreilly.co.jp/books/97848731… @oreilly_japanさんから

2016-07-24 18:21:13
. @senopen

次からはSphinxをはじめようを読んで勉強しよう。

2016-07-26 00:23:42
. @senopen

2015/05/21 #PyPro2 の電子書籍が出ました! - Pythonプロフェッショナルプログラミング第2版 - 清水川Web - freia.jp/taka/blog/pyth…

2016-07-26 09:43:41
. @senopen

Sphinxを使用しているプロジェクト — Sphinx 1.4.4 ドキュメント - docs.sphinx-users.jp/examples.html

2016-07-26 09:55:00
. @senopen

RT @togetter_jp: C++向けドキュメンテーションツールの悩み覚書 - Togetterまとめ togetter.com/li/141233

2016-07-26 09:55:53
. @senopen

Is Sphinx already suitable for C++ documentation? - Stack Overflow - stackoverflow.com/questions/1293…

2016-07-26 09:59:52
. @senopen

GitHub - michaeljones/breathe: ReStructuredText and Sphinx bridge to Doxygen - github.com/michaeljones/b…

2016-07-26 10:12:06
. @senopen

Sphinx FAQ — Sphinx 1.4.5 ドキュメント - sphinx-doc.org/ja/stable/faq.…

2016-07-26 10:15:33
残りを読む(23)

コメント

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