pyusb 1.0 ドキュメント日本語訳(2021年)

#ブツ
ブツはコチラ。

本家とちょっと違います

本家のドキュメントはapiはdocstringを自分でpydocなりして読んでねということでapiリファレンス載せなくなっちゃったので、autoapiして掲載しました。

#以下作り方メモ
興味ある人だけどうぞ。

sphinx-intlまで

本家(?)pyusbをforkします。

名前をpyusb-docs-jaにしました。

branch切ります。docs-ja 以降docs-ja branchで作業します

venv環境造ります。 python3 -m venv venv

activateしてpip -U pip, sphinx, sphinx-intl, sphinx-autoapi

元々あるdocsフォルダにsphinx環境造ります。

READM.rstを ln -s ../README.rst しておきます。

conf.py編集してsphinx-intl対応しておきます。

.gitignoreも設定しておきましょう。

sphinx-qucikstart

できたらとりあえずmake htmlしてみます。
手元の環境では _static フォルダが無いって怒られたので空のフォルダ作っておきます。

autoapi

さて、autoapi関係です。conf.pyの後ろの方に下記のように追加して、make html すると、中間ファイルとしてautoapiフォルダにapiのrstファイルを造ります。これは1度だけ実行します。再度実行すると黙って上書きしやがります。

conf.py

# for autoapi
extensions.append('autoapi.extension')
autoapi_type = 'python'
autoapi_dirs = ['../usb',]

# Once you have built your documentation with this option turned on,
# you can disable AutoAPI altogether from your project.
autoapi_keep_files = True

なので、1度実行したら conf.pyの上記部分を丸ごとコメントアウトします。

conf.py

# for autoapi
# extensions.append('autoapi.extension')
# autoapi_type = 'python'
# autoapi_dirs = ['../usb',]

# Once you have built your documentation with this option turned on,
# you can disable AutoAPI altogether from your project.
# autoapi_keep_files = True

しかし、そうするとエラーが大量にでます。なんでかというとautoapiで生成すると .. autoapihogehoge というディレクティブが大量に入り込むからです。auotapiをコメントアウトしたら当然これらは使えません。

そしてautoapiにできたものをapiフォルダに丸ごとコピって、以後はそちらをいじります。api/index.rstのtoctreeはautoapiフォルダを指してたりするので各自チェック願います。

本家で更新あったときはpullしてその後、conf.pyでまた上記を有効にして make html 実行してすぐコメントアウトします。そしてautoapiの内容とapiの内容をdiffして更新掛けます(めっさ手動)。

翻訳は

make gettext
sphinx-intl update -p _build/gettext

であとはひたすらlocale下のpoファイル達を訳すだけです。

原文を修正したら再度上記を行いましょう。

readthedocsへ公開

readthedocs側でこのgithubのリポジトリを指定する。

conf.pyのlanguage設定はenのままにしておきます(あるいは当該設定を省略した場合'en'扱い)。readthedocs側のproject homeの管理の設定の言語があるのでそこをJapaneseにすると language=ja として生成してくれます。

なお、readthedocsはWebのキャッシュが強力なのか、何度かリロードしないと変更結果が反映されないことがありました。

#以前の翻訳版から翻訳をできるだけ持ってくる。
ごりごりと手動でmsgmerge書いて持ってきました。apiリファレンス部分の対応は旧ドキュメントと今回で若干ファイル構成が違うので単純に1対1の対応になっていません。

msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/README.po ../../pyusb-docs/locale/ja/LC_MESSAGES/README.po _build/gettext/README.pot
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/tutorial.po ../../pyusb-docs/locale/ja/LC_MESSAGES/docs/tutorial.po _build/gettext/tutorial.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/faq.po ../../pyusb-docs/locale/ja/LC_MESSAGES/docs/faq.po _build/gettext/faq.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.po _build/gettext/api/usb/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/core/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.po _build/gettext/api/usb/core/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/control/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.po _build/gettext/api/usb/control/index.pot
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/backend/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.backend.po _build/gettext/api/usb/backend/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/backend/libusb0/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.backend.po _build/gettext/api/usb/backend/libusb0/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/backend/libusb1/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.backend.po _build/gettext/api/usb/backend/libusb1/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/backend/openusb/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.backend.po _build/gettext/api/usb/backend/openusb/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/legacy/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.po _build/gettext/api/usb/legacy/index.pot 
msgmerge --previous --lang=ja_JP -o locale/ja/LC_MESSAGES/api/usb/util/index.po ../../pyusb-docs/locale/ja/LC_MESSAGES/api-docs/usb.po _build/gettext/api/usb/util/index.pot