リファレンスの機能

[tubo28]

7 ではたたき台として Python を使って列挙するようにしてもらった。

使えるところまで持っていくにあたり何がほしいか？方法とその手間はどのくらいか？

[tubo28]

ブラウザでの閲覧とエディタにコピペするような使われ方を想定すると、あると良さそうな機能として

• 一覧
• 検索
• シンタックスハイライト
• コピーボタン
• ファイルの説明
• 関数やクラスの説明
• コピーするときに依存するファイルを解決して 1 つのテキストにまとめる

などが考えられますが、それぞれどうやって実現しましょう？ 下に色々書いてみましたが Doxygen (使ったこと無い) 等の既存のツールでできるものがあるなら教えてほしいです。

一覧

generate-docs.py でやっているので HTML に整形すればよさそうです。

検索

とりあえず一覧に対してブラウザの Ctrl-F 機能を使えばできます。検索ボックスを組み込むライブラリも探せばありそうです。

シンタックスハイライト

クライアントサイド (higilight.js)？サーバーサイド (pygmentize)？ 経験上 pyementize を使う場合はキャッシュしないと重いです。

コピーボタン

AtCoder や yukicoder を参考にすればできると思います。

ファイルの説明

ファイルの冒頭に書かれたコメントを HTML に表示するくらいならできそうです。

関数やクラスの説明

ここまで来ると Python で自作パーサーを作るのは辛くなってきます。

依存するファイルを解決して 1 つのテキストにまとめる

どのように実現するのが良いのでしょう？ @require [filename] のようなノーテーションを定義し、トポロジカルソートすればできそうではあります。

[kyuridenamida]

サイト全体の全文検索としてまずはグーグル検索使うのもありなんじゃないかって思ってますが、どうでしょう

[kyuridenamida]

@requireという特殊なアノテーションよりは、#includeをそのまま置き換える方が、ローカルでの分割ファイル状態でのコンパイルとかを考えたときに良かったりしませんかね？

[kyuridenamida]

僕は実はdoxygen知らなくてjavadocしか知らないんですがドキュメントはソースコード中に書いたらそれが自動でリファレンスになるdoxygen的なやつが、メンテナンス性も利便性も高いと思います

[asi1024]

@requireという特殊なアノテーションよりは、#includeをそのまま置き換える方が、ローカルでの分割ファイル状態でのコンパイルとかを考えたときに良かったりしませんかね？

多言語対応したときにこういうやつで統一したくなりそう，という経緯です

[asi1024]

依存するファイルを解決して 1 つのテキストにまとめる

どのように実現するのが良いのでしょう？ @require [filename] のようなノーテーションを定義し、トポロジカルソートすればできそうではありあます。

./bin/preprocessor.py [filename] でできます

[tubo28]

doxygen やってみました 良さげなページが出力されています (私のサーバーにIPアドレスが残っても気にならない人は→ https://tubo28.me/public/doxygen/html/) 今後適切に Doxyfile を設定して CI に生成コマンドを追加したいです

ところで、上にも書きましたが依存を全て解決した上でクリップボードにコピーするようなボタンが欲しく、 doxygen でそれを実現するよい方法って何なんでしょうか？

• preprocessor.py で依存を解決したファイルを用意しておく
• doxygen -w html ... で任意のヘッダーを流し込めるようなので JavaScript でファイルへのリンクやコピーボタンを追加する

くらいならできますが筋はあまり良くないような

[tubo28]

上で使った Doxyfile https://gist.github.com/tubo28/d1fc434812cac3054475e9e5669aa044

[asi1024]

複数のファイルを使いたいとき，それぞれにプリプロセサをかけてから結合すると，重複ができてしまう可能性があります．なので，preprocessor.py が複数のファイルを引数にとれるようにしたいです．

[tubo28]

サーバーを立てて動的に生成するということですか？