tsutaj / cpp_library Goto Github PK

見栄えが悪いと言うだけ (運用上は特に問題ないと思う) (優先度だいぶひくい)

コードにコピーボタンがついてないのつらくない？

コードが汚いのでなんとかする、実装すべきものの要件をまとめよう

想定するディレクトリ構成

ディレクトリ構成からしてすでにぐちゃぐちゃなので、直してえ

source/
md-output/
build-pages.py (現在の generate_readme.py)
lib/
|-- sh/
|-- css/
|-- js/

• source/
  • library file
    • 競プロのライブラリファイル
    • 拡張子は *.cpp
  • verify file
    • ライブラリの正当性を確認するファイル
    • 拡張子は *.test.cpp
• build-pages.py
  • source-dir (必須)、destination (デフォルトは md-output/) を渡して、source-dir の中身を Markdown 化して destination フォルダに出力
• lib/
  • build-pages.py の実行に必要なものを格納するところ？実装しながら細かいところ詰めたい

タグ

• @file: 該当するファイルの名前 (設定されていればこれをタイトルとし、設定されていなければファイル名をタイトルとしたい)
• @brief: 一行程度の簡単な説明
• @see: 問題の URL
  • Doxygen に @sa、@see という command があって、それと機能がちょっと似ていそう？記法合わせたほうがいいのかなぁ
• @docs: ファイルについて説明した Markdown ファイルへのリンク [要検討]
  • @brief よりも長い文章を書くことを想定
• @depends: 依存関係
  • verify file に関しては、@depends は #include されているものから類推できそう

build-pages.py について

やること

大まかに書く

1. library-dir と verify-dir から対象となるファイルをそれぞれ読み込む
   • 「@file」=>「build-pages.py から該当ファイルへの相対パス」という対応関係を得る
   • 上記の逆となる対応関係も得る
   • 別ファイルで同じ内容の @file を書くと破滅しそう、その場合は適当にナンバリング？
2. verify-dir の中にある要素についてページをビルドする
   • このときに、verify file の dependency を見ることで各 library file がどの verify file で使われているかが分かるため、それを覚える
3. library-dir の中にある要素についてページをビルドする

やらないこと

• CI と連携して push させたりする
  • ローカルで試しに Markdown 生成してみる需要もなくはなさそうだし、このへんの処理は別ファイルに切り離してやりたい？あくまでファイルを吐くところまでが担当な気がしている

各コードについて、使い方とかを説明できる仕組みがあると嬉しい

ファイルの頭に

#define DOCS "/path/to/docs/file.md"

とかをつけて、そのファイルを読み込んで貼り付けるとか