Documents of MISO (Mhd ISee Open source code), an open-source software for performing magnetohydrodynamics (MHD) simulations.
C++のAPIドキュメントをdoxygenで、pythonのAPIドキュメントをsphinxで生成する。全体のフォーマットを揃えるためにdoxygendenではxml形式で出力し、sphinxで取り込む。
sphinx + breathe + exhaleを利用
以下のパッケージをインストール
sudo apt update && sudo apt install -y doxygen
pip install sphinx sphinx-rtd-theme sphinx-automodapi sphinx-multiversion breathe exhale sphinx-copybutton sphinxcontrib-bibtex myst-parser make -C docs htmlこれでdocs/build/index.htmlにHTMLが生成される。
sphinxcontrib-bibtex を利用して、参考文献を管理している。
参考文献は docs/source/reference.bib に記載して、
:cite:`sod_1978JCoPh..27....1S`として引用する。
原文は日本語で書き、英語版は Sphinx の gettext で別にビルドする。訳は docs/locale/en/LC_MESSAGES/*.po に置き、git で管理する。
api/（Doxygen と automodapi の出力）は訳さない。訳がない段落は日本語のまま出る。
pip install sphinx-intl
make -C docs html # 日本語版（Doxygen の XML と source/api もここで作る）
make -C docs update-po # 原文の変更を .po に反映する
make -C docs po-todo # 訳し直しが要る項目を並べる
make -C docs html-en # 英語版を docs/_build/html/en に作る訳語と訳し方の決まりは docs/locale/glossary.md にある。訳すとき（LLM で訳すときも）はこのファイルを渡す。
LLM で訳すときは、必ず Claude Sonnet 以下のモデル（Sonnet・Haiku）を使う。
-
日本語の原文を直す（
docs/source/の.md・.rst）。 コードブロックの中（コメント・出力例・図）は英語で書く。コードブロックは訳の対象にならないので、日本語版でも英語のまま出る。 -
日本語版を確かめる：
make -C docs htmlを実行し、docs/_build/html/を見る。 -
.poに反映する：make -C docs update-poを実行する。 直した段落の訳は fuzzy（#, fuzzyの印がつき、前の訳が残る）か、未訳（msgstr ""）になる。fuzzy の訳はビルドで使われない。 -
訳し直す：
make -C docs po-todoで、訳し直しが要る項目を見る。その項目だけを訳し、#, fuzzyの行を消す（#|で始まる前の原文の行があれば、それも消す）。 Claude Code で訳すときは、たとえば次のように頼む。make -C docs po-todoに出る項目を、docs/locale/glossary.mdに従って訳して。訳は Sonnet のサブエージェントで行い、msgstr だけを変えること。終わったらmake -C docs html-enで警告が増えないことを確かめて。訳さずに PR を出してもよい。そのときは、その段落は英語版でも日本語のまま出る。PR の説明にそう書く。
-
英語版を確かめる：
make -C docs html-enを実行し、docs/_build/html/en/を見る。make -C docs po-todoが何も出さなければ、訳し残しはない。 -
原文と
.poを同じ PR に入れる。git diff docs/localeで、変わったのが直した段落のmsgidとmsgstrだけであることを確かめる。 PR を出すと、日本語版はhttps://is-isee.github.io/MISO_docs/pr-<番号>/、英語版は.../pr-<番号>/en/で見られる。 訳のレビューは、直した段落だけを見ればよい。
GitHub Pagesで公開する場合は、.github/workflows/deploy_pages.ymlを利用する。mainブランチにpushすると、gh-pagesブランチに自動的にデプロイされる。正式版はhttps://is-isee.github.io/MISO_docs/（英語版はhttps://is-isee.github.io/MISO_docs/en/）、PR版はhttps://is-isee.github.io/MISO_docs/pr-${pr}/からアクセス出来る。