上野家のホームページ - 資料室バックアップ : 開発/Python/Pythonドキュメントのソース

[ 差分 | バックアップ | リロード ]
差分を表示
開発/Python/Pythonドキュメントへ行く。
* Pythonのドキュメントの日本語化とヘルプファイル [#j419f555]
私はPython初心者で，''Pythonの公式ドキュメント''をマニュアルとしてよく見る。~
公式オリジナルの英語版が https://docs.python.org/3/ で公開されていて，その日本語に翻訳されたものが https://docs.python.jp/3/ で公開されている。~

PythonをインストールするとWindowsのヘルプファイルも提供されるが，日本語翻訳したものは公式にはリリースされていないみたい。

一応，[[Python Japanese Environment>https://ja.osdn.net/projects/pythonjp/]]で，Python 2.7の日本語Windowsヘルプファイルがあるのだが，なぜかエラーが毎回表示されてしまう。また，最新のバージョンのものは残念ながら見つからない。

そこで，日本語翻訳されたWindowsのヘルプファイルを作成してみることにした。

[[Pythonドキュメント日本語訳プロジェクト>https://github.com/python-doc-ja/python-doc-ja]]の活動のおかげで，日本語訳のリソースは手に入れることが出来る。~
これを使用して，日本語のPythonのヘルプファイルを作成してみる。

* ソースコードと日本語リソースを用意する [#vb732b95]
まず，Pythonのドキュメントから日本語のドキュメント（HTML）を作成してみる。

** ビルドに必要なツールを用意する [#zeba009d]
ドキュメントを作成するのに必要なツールSphinx（Pythonで動作する）やTransifex（翻訳プロジェクト）などを，インストールする。
 > pip install sphinx
 > pip install sphinx-intl
 > pip install blurb
 > pip install transifex-client

** Pythonのソースコードを準備 [#p0d51217]
Pythonのドキュメントを作成するのに，Pythonのソースコードにドキュメントのソースも含まれているので必要になる。

Pythonの[[公式サイト>https://www.python.org/]]から，Pythonのソースコード（ドキュメントも含んでいる）をダウンロードする。これには，日本語翻訳されたドキュメントのリソースを含んではいない。~
適当な作業ディレクトリで解凍する。
 > wget https://www.python.org/ftp/python/3.7.2/Python-3.7.2.tgz
 > tar xvfz Python-3.7.2.tgz
 > cd Python-3.7.2

別の方法として，[[Pythonドキュメント日本語訳プロジェクト>https://github.com/python-doc-ja/cpython-doc-intl]]から，Sphinxの設定が含まれたPythonのソースコードをダウンロード出来る。~
ただ，翻訳作業が終了後にリポジトリが更新されるので，最新バージョンが用意されるまでは時間がかかる。いまのところ用意されている最新版は3.6.5だった。
 > git clone https://github.com/python-doc-ja/cpython-doc-intl
 > cd cpython-doc-intl
 > git checkout intl-3.6

** Sphinxの設定ファイルを修正 [#e1844232]
Sphinxを使用して日本語ドキュメントが出力されるように，''conf.py''ファイルの''General configuration''のどこかに，以下の追加・修正をする。
 language = 'ja'
 locale_dirs = ['locale/']
 gettext_compact = False
  ：
  ：
 today_fmt = '%m/%d/%Y'

** 翻訳済みリソースをTransifexからダウンロードする [#sb5a1327]
Pythonの[[公式サイト>https://www.python.org/]]からのソースコードには日本語化したドキュメントが入っていない。Pythonドキュメントプロジェクト [[transifex>https://www.transifex.com/python-doc/]] で日本語の翻訳作業が行われているので，そこから日本語訳リソースをダウンロードする。

Pythonドキュメントプロジェクト [[transifex>https://www.transifex.com/python-doc/]] に参加して，翻訳作業を行うことが出来る。翻訳作業は大変な労力が必要なので多くの人の協力が必要。参加したいなぁ。

Pythonドキュメント日本語訳プロジェクトのリソースを使う場合は，[[transifex>https://www.transifex.com/]]のアカウントを作成する必要はない。

まず，[[transifex>https://www.transifex.com/]] でアカウントを作成する。アカウントが作成できたらAPIキーを作成しておく。翻訳者として登録しない場合は，アカウントを使用できるのは''15日間''。~
''~/.transifexrc''ファイルを以下の内容で作成する。
 [https://www.transifex.com]
 hostname = https://www.transifex.com
 token = xxxxxxxxxxxxxx
 username = <ユーザー名>
 password = <パスワード>
tokenには，作成したAPIキーを設定する。

翻訳のチームに参加ボタンを押して参加を表明し，承認されれば（メールで送られてくる），翻訳リソースをダウンロードできるようになる。~
Pythonドキュメントプロジェクト [[transifex>https://www.transifex.com/python-doc/]] での翻訳作業の成果を， [[Pythonドキュメント日本語訳プロジェクト>https://github.com/python-doc-ja/python-doc-ja]] に公開しているようだ。~

翻訳するための設定ファイル.tx/configファイルを作成する。
 > cd locale 
 > sphinx-intl create-txconfig
 
Pythonドキュメントソースからメッセージカタログ（.pot）ファイルを作成する。~
 > cd ..
 > sphinx-build -b gettext . locale/pot

翻訳するための設定ファイル.tx/configファイルをpotファイル情報で更新する。
 > cd locale
 > sphinx-intl update-txconfig-resources --pot-dir pot --transifex-project-name="python-newest"
 > awk '/file_filter/{sub("locales/","");print $0} !/file_filter/{print $0}' .tx/config > .tx/config.2
 > cp .tx/config.2 .tx/config
 > rm .tx/config.2
 > tx pull -l ja
とすると，現在翻訳作業中の翻訳リソースの.poファイルがダウンロードできる。

*** Pythonドキュメント日本語訳プロジェクトのリソースを使う場合 [#n16ba263]
[[Pythonドキュメント日本語訳プロジェクト>https://github.com/python-doc-ja/python-doc-ja]]のリポジトリに日本語訳されたドキュメントリソースがある。最新はバージョン3.6.5。このバージョンで良ければ，以下のようにして.poファイルをダウンロードする。~
 > cd Doc
 > git clone https://github.com/python-doc-ja/py36-locale locale
.poファイルは，Doc/locale/ja/LC_MESSAGES/にダウンロードされる。

バージョン3.7.2の場合は，
 > cd Doc
 > git clone https://github.com/python-doc-ja/py37-locale locale
とすれば良いと思われるが，残念ながらまだリポジトリにアップされていない。（翻訳作業自体は進んでいる。）

* 日本語ドキュメント（HTML）を作成 [#w722d888]
''conf.py''ファイルのOptions for HTML outputに，以下の修正をする。
 html_last_updated_fmt = '%m/%d/%Y'

翻訳した.poファイル（実際には.moファイル）を使用して，ドキュメントファイル（HTMLファイル）をビルドしてみる。~
 > make clean html

自分で翻訳を修正したりしたい場合は，Doc/locale/ja/LC_MESSAGES/にある.poファイルを，好みに編集してビルドすれば良い。

これでうまく行けば，''日本語訳されたHTMLのドキュメント''がDoc/build/htmlに作成される。

* Windowsのヘルプファイルchmを作成する [#s57c9c9b]
HTMLのドキュメントが作成出来れば，Windowsで使われるヘルプファイルである.chmファイルを作成できる。

作成するには，Microsoftの [[HTML Help Workshop>https://www.microsoft.com/en-us/download/details.aspx?id=21138]] が必要になる。

** .chmファイルを作成する [#a6884bf6]
DocディレクトリにMakefile等があるので，それを使ってHTML Help Workshopが使用するプロジェクトファイルを作成する。
 > make htmlhelp
Doc\build\htmlhelpに，HTMLファイルとpythonxxx.hhp，pythonxxx.hhc，pythonxxx.hhk，pythonxxx.stpが作成されている。

''pythonxxx.hhp''をダブルクリックしてHTML Help Workshopを起動しコンパイルすれば，Doc\build\htmlにpythonxxx.chmファイルが作成される。

この時，locale以下に翻訳リソースがない場合，''build/htmlhelp''ディレクトリには英語のHTMLファイルがセットされてしまう。当然，HTML Help Workshopでコンパイルしても日本語ヘルプファイルにはならない。~

もし日本語化されたHTMLファイルが''build\html''にある場合，''build\htmlhelp''出来たpythonxxx.hhp，pythonxxx.hhc，pythonxxx.hhk，pythonxxx.stpを，''build\html''にコピーして''build\html''のpythonxxx.hhpをダブルクリックしてHTML Help Workshopを起動しコンパイルすれば，ほぼ日本語化されたpythonxxx.chmファイルを作成することもできる。

* LaTeXを使ってPDFファイルを作成する [#dac558c6]
Sphinxでは，[[LaTeX>https://ja.wikipedia.org/wiki/LaTeX]]を使用してTeX日本語ドキュメントを出力出来て，そこからPDFファイルを作成できる。~
この場合，LaTeX（[[W32Tex>https://texwiki.texjp.org/?W32TeX]]を使ってる）やその他の周辺ツール，スタイルファイルなどが必要になる。

設定ファイル''conf.py''の''Options for LaTeX output''で，使用するエンジン''xelatex''をコメントアウトする。
 #latex_engine = 'xelatex'
これは，デフォルトの''platex''を使うようにするため。

Sphinxのクラスにhowtoとmanualがあって，howtoが短い文書，manualが長い文書に利用されているようだ。~
使用するドキュメントクラスは，デフォルト設定のhowtoに''jreport''，manualに''jsbook''が使われる。変更したい場合は，
 latex_docclass = {"howto": "jsreport", "manual": "jsbook"}
のように設定する。

Pythonのドキュメントには，İ (U+0130)， ı (U+0131)， ſ (U+017F)， K (U+212A)， Ü (U+00DC)， ü (U+00FC) ， Є (U+0404) の非ASCii文字が含まれている。~
これらをPDFで出力するために，''conf.py''のプリアンプル''latex_elements['preamble']''に，以下のように追加する。
 latex_elements['preamble'] = r'''
 \authoraddress{
   \sphinxstrong{Python Software Foundation}\\
   Email: \sphinxemail{docs@python.org}
 }
 \let\Verbatim=\OriginalVerbatim
 \let\endVerbatim=\endOriginalVerbatim
 \usepackage[TS1,T1,T2A]{fontenc}
 \usepackage{lmodern}
 \usepackage[utf8]{inputenc}
 \usepackage{babel}
 \DeclareUnicodeCharacter{212A}{\ensuremath{\mathrm{K}}}
 \DeclareUnicodeCharacter{017F}{{\fontencoding{TS1}\selectfont s}}
 \DeclareUnicodeCharacter{0404}{\fontencoding{T2A}\CYRIE}
 '''
//ただ，Є (U+0404) を表示する仕方がわからない。しょうがないんで，この文字はεでドキュメントのソースコード（locale\ja\LC_MESSAGES\whatsnew\3.7.po）を修正した。

いくつかの.texファイル（library.tex，howto-logging.tex，using.tex）で，画像を読み込んでいるところでエラーが出るので，''conf.py''の''Options for LaTeX output''に，以下を追加する。
 latex_elements['passoptionstopackages'] = r'''
 \usepackage[dvipdfmx]{graphicx}
 '''

** texファイルを作成して，さらにpdfファイルを作成する [#ab6bf0be]
DocディレクトリにMakefile等があるので，それを使ってtexファイルを作成する。
 > make latex PAPER=a4
この時，文書サイズをA4かletterか指定できる。~
うまくいくと，build/latexディレクトリに.texファイルが作成されている。

texファイルからPDFファイルに変換してみる。
 > cd build/latex 
 > make all-pdf-ja
これで，うまく行けばPDFファイルが作成される。

* 作成した日本語ドキュメント [#v8d8ec6c]
作成したバージョン3.7.2の日本語ヘルプファイル：&ref(python372jp.chm);
« Prev
開発/Python/Pythonドキュメントのバックアップ一覧
開発/Python/Pythonドキュメントのバックアップソース(No. All)
- 1: 2019-02-15 (金) 08:16:51 yuji
- 2: 2019-02-15 (金) 08:19:37 yuji
  - Attached file: python372jp.chm, Deleted an attach file: python372jp.chm at 2019-02-20 (水) 08:35:58
- 3: 2019-02-19 (火) 23:36:10 yuji
  - Attached file: python372jp.chm, Deleted an attach file: python372jp.chm at 2019-02-21 (木) 13:46:13
- 現: 2020-12-26 (土) 16:07:39 yuji
  - Attached file: python372jp.chm
Counter: 1727, today: 1, yesterday: 0
ログイン
パスワード紛失
メインメニュー
開発​/Python​/Pythonドキュメント のソース

開発/Python/Pythonドキュメントのソース
