本記事について

本記事では Sphinx の開発環境を作り、ついでにCI環境を構築する手順を紹介します。

私自身が Python を扱う機会がないため、Python の仮想環境について調べた結果も紹介しています。そのため Python について知識が少ない人を対象としています。

ここで作成した Sphinx のソースコードは GitHub で紹介しています。

技術スタックについて

以下のバージョンを使用しました。

Python 3.7
Sphinx 2.1.2
pipenv 2018.11.26

poetry を使う方法を追記しました ('20/05/24)

Python 3.7
Sphinx 2.1.2
poetry 1.0.5

Sphinx とは

Sphinx は Python のソースコードを公開するために作成された静的ドキュメントジェネレータです。

reStructuredText で記述したドキュメントをコンパイルすることで、HTML/PDF を生成することが出来ます。

構造化されたドキュメント形式を使いつつ、HTML にコンパイルすることで Web サーバだけでドキュメントを公開できるのがメリットと言えます。

Sphinx 環境の構築 (pipenv版)

Sphinx は Python パッケージです。
そのためコンパイルするためには Python が必要です。

Sphinx 環境を構築するために Python 環境を構築する必要があります。

Python とパッケージの実行環境について

Python はパッチバージョン(X.Y.ZのZ)が上がると上書きされ、マイナーバージョン(X.Y.ZのY)が上がると複数のバージョンがインストールされます。

また Python パッケージを管理するコマンドとして pip があり、依存パッケージを requirements.txt に記述して、インストール時に参照してパッケージをインストールすることで管理します。

Python のバージョン及び Python パッケージは Python を実行する環境ごとに分けることが出来ると便利です。

ツール名	Pythonの管理	Pythonパッケージの管理	備考
pyvenv	△	〇	Python 3.4, 3.5までの推奨
venv	×	〇	Python 3.6以降で推奨
virtualenv	△	〇	サブセットは Python 3.3 以降の venv の標準ライブラリとなった参考
pipenv	△	〇	内部で virtualenv を使っていて pip と virtualenv を連動して扱えるパッケージの依存関係を pip より賢く管理できる dependabot が対応している
pyenv	〇	×
Anaconda	〇	〇
poetry	△	〇	パッケージの依存関係を pipenv より賢く解決できる dependabotが対応している
pyflow	〇	〇	Rust 製であり Python の挙動に依存しない実行時に設定された Python がなければインストールされる dependabot が対応していない

※ Python の管理について〇はホストに複数 Python バージョンをインストールできることを示し、△ は使用する Python バージョンを固定できることを示します。

Python 実行環境を構築する

pyenv 又は Anaconda をインストールして複数の Python をインストールできるようにします。

Windows に pyenv をインストールする方法
- Anaconda をインストールする
- Anaconda の仮想環境を作成する(GUI操作)
Ubuntu に pyenv をインストールする方法
- https://github.com/pyenv/pyenv#installation
Mac OS に pyenv をインストールする方法
- brew update
- brew install pyenv

Python をインストールする。※ pyenv のコマンドリファレンスは備考を参考にしてください

PythonX.Y.Zをインストールしてグローバルに使用するPythonバージョンを指定する

$ pyenv install X.Y.Z
$ pyenv global X.Y.Z

(必要に応じて)pyenvでグローバルに使うPythonバージョンを確認する

$ pyenv global
X.Y.Z

尚、ここで Python をインストールしなくても pipenv コマンドが仮想環境を作成する時に pyenv を使ってインストールすることも出来ます。

pipenv をインストールして仮想環境を構築する

pipenv をインストールしてパッケージを仮想環境ごとに管理できるようにします。

pipenv は Python パッケージなので pip コマンドでインストールできます。

$ pip install pipenv

Python のバージョンを指定して pipenv コマンドを実行すると仮想環境が作成されます。

このとき、仮想環境はカレントディレクトリに対応して作成されるため予め仮想環境で管理したいディレクトリに移動してからコマンドを実行します。

$ cd ＜仮想環境を作成して管理したいディレクトリへ移動する＞
$ pipenv --python X.Y  # X.Y は仮想環境で使う Python のバージョンを指定する。

以降、pipenv コマンドを実行する場合は仮想環境を作成したディレクトリ配下で実行する必要があります。(本記事内ではcdコマンドは記載しません)

コマンド実行時のメッセージにも書かれていますが、カレントディレクトリには Pipfile が作成されますが、仮想環境は別ディレクトリに作成されます。
pipenv による仮想環境についての補足情報は備考も参考にしてみてください。

✔ Successfully created virtual environment!
Virtualenv location: /home/vagrant/.local/share/virtualenvs/p3.5-AsS0v8Ts

尚、先に記述したとおり pipenv コマンドで仮想環境を作成する時に指定した Python がインストールされていない場合に pyenv を使って Python をインストールすることが出来ます。

pipenvコマンドで仮想環境を作成する時にpyenvを使ってPython3.5がインストールされる例

$ pipenv --python 3.5
Warning: Python 3.5 was not found on your system…
Would you like us to install CPython 3.5.7 with pyenv? [Y/n]: 
Installing CPython 3.5.7 with pyenv (this may take a few minutes)…
✔ Success! 
Downloading Python-3.5.7.tar.xz...
-> https://www.python.org/ftp/python/3.5.7/Python-3.5.7.tar.xz
Installing Python-3.5.7...
WARNING: The Python bz2 extension was not compiled. Missing the bzip2 lib?
Installed Python-3.5.7 to /home/vagrant/.pyenv/versions/3.5.7


Creating a virtualenv for this project…
Pipfile: /home/vagrant/work/pipenv/p3.5/Pipfile
Using /home/vagrant/.pyenv/versions/3.5.7/bin/python3 (3.5.7) to create virtualenv…
⠧ Creating virtual environment...Already using interpreter /home/vagrant/.pyenv/versions/3.5.7/bin/python3
Using base prefix '/home/vagrant/.pyenv/versions/3.5.7'
New python executable in /home/vagrant/.local/share/virtualenvs/p3.5-AsS0v8Ts/bin/python3
Also creating executable in /home/vagrant/.local/share/virtualenvs/p3.5-AsS0v8Ts/bin/python
Installing setuptools, pip, wheel...
done.
Running virtualenv with interpreter /home/vagrant/.pyenv/versions/3.5.7/bin/python3

✔ Successfully created virtual environment! 
Virtualenv location: /home/vagrant/.local/share/virtualenvs/p3.5-AsS0v8Ts
Creating a Pipfile for this project…

Sphinx パッケージをインストールする

Sphinx をインストールします。

Sphinx は Python パッケージなので pip コマンドでインストールできますが、pipenv を使います。

$ pipenv install sphinx  # 仮想環境が作成されていない場合は作成される

Sphinx を初期化してHTMLドキュメントを作成する

Sphinx公式ドキュメントの「はじめに」に従います。

ソースコードとビルドスクリプトを作成する

$ pipenv run sphinx-quickstart

sphinx-quickstart コマンドを実行するとクイックスタートユーティリティが実行され、プロジェクトの設定をいくつか入力すると Sphinx のソースコードとビルドスクリプトが作成されます。

設定は default でよいと思いますが、ソースディレクトリはカレントディレクトリ以外(srcなど)にすることをお勧めします。

本記事の後続でも説明しますが、ソースコードが仮想環境と同じディレクトリにある場合に、仮想環境内のファイルをソースコードの一部として認識しようとしてビルド時にいくつかの warning が発生する issue が存在するためです。

sphinx-quickstart実行後のディレクトリ構造

.
├── Makefile       ... ビルド時に使うmakeコマンド用の設定ファイル(主にLinux用)
├── Pipfile
├── Pipfile.lock
├── build          ... ビルド結果を格納するディレクトリ(設定内容次第で名前は変わる)
├── make.bat       ... ビルド時に使うmakeコマンド用のバッチファイル(Windows用)
└── source         ... ソースディレクトリを格納するディレクトリ(設定内容次第で名前は変わる)
    ├── _static    ... ビルド結果にコピーしたいファイルを格納するディレクトリ
    ├── _templates ... Sphinxのテンプレートを格納するディレクトリ
    ├── conf.py    ... Sphinx用設定ファイル
    └── index.rst  ... Sphinxソースファイル

将来的に Sphinx ドキュメントの自動ビルド設定を追加したい場合等には Makefile, make.bat を修正することになると思いますが、make.bat の中を見ると分かるように goto を使う等、メンテナンスがしづらいため、本記事では Makefile, make.bat は初期状態のままにして pipenv の script を使うことにします。

ここで、VCS を使っている場合は build ディレクトリを対象外にするように ignore ファイルを作成しておきましょう。

.gitignore

build

HTML をビルドしてみる

sphinx-quickstart コマンドを実行すると、サンプルとなる Sphinx ソースコードがあるのでビルドが出来ます。

$ pipenv run make html
Sphinx v2.1.2 を実行中
出力先ディレクトリを作成しています... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
ビルド中 [html]: 更新された 1 件のソースファイル
環境データを更新中1 件追加, 0 件更新, 0 件削除
ソースを読み込み中...[100%] index                                                                                                                                      
更新されたファイルを探しています... 見つかりませんでした
環境データを保存中... 完了
整合性をチェック中... 完了
preparing documents... 完了
出力中...[100%] index                                                                                                                                            
索引を生成中... genindex
追加のページを出力中... search
静的ファイルをコピー中... 完了
extraファイルをコピー中...完了
English (code: en) の検索インデックスを出力...完了
オブジェクト インベントリを出力...完了
ビルド 成功.

HTMLページはbuild/htmlにあります。

build/html 配下に HTML ファイルが作成されています。
build/html/index.html をブラウザで開いて見ると Sphinx ドキュメントが表示されることが確認できます。

Sphinx にテーマを適用する

Sphinx はテーマを適用することでスタイルを変更できます。参考

標準のテーマもいくつかありますが、ここでは Sphinx 1.4 からサードパーティとなった sphinx-rtd-theme を適用します。

sphinx-rtd-theme は Python パッケージなので pipenv でインストールできます。

pipenv install sphinx-rtd-theme

次に Sphinx のテーマ設定を変更します。
必要なのは conf.py の html_theme にテーマ名を設定するだけです。

conf.py

  : <snip>
# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
  : <snip>

以上でテーマの適用は終わりです。

設定が終わったら pipenv run make html コマンドを実行して HTML ファイルをビルドして build/html/index.html をブラウザで開いてみて下さい。
テーマが適用されていることが確認できると思います。

ビルド環境を改善する

テーマの適用を行ったときのように、ソースコードを変更した後に結果をブラウザで確認するためにはビルドを行う必要があります。

出来れば、ブラウザを開いたままソースコードに変更があったら自動でビルドを実行して、ビルド結果をブラウザで確認したいと思うはずです。

Sphinx ドキュメントを自動でビルドするための Python パッケージとして sphinx-autobuild があるので使うことにします。

sphinx-autobuild をインストールする

sphinx-autobuild は Python パッケージなので pipenv コマンドでインストールできます。

$ pipenv install --dev sphinx-autobuild

sphinx-autobuild コマンドを実行すると Web サーバが起動し、ソースコードに変更があるか watch し始めて変更があると自動でビルドされます。

$ pipenv run sphinx-autobuild source build

起動時に次のメッセージがあるとおり、 http://127.0.0.1:8000 をブラウザで開くとビルド結果を表示することが出来ます。(0.0.0.0:8000となっていた場合はlocalhostに読み替えればよいです)

[I 190816 00:29:13 server:296] Serving on http://127.0.0.1:8000
[I 190816 00:29:13 handlers:62] Start watching changes
[I 190816 00:29:13 handlers:64] Start detecting changes

試しに source/index.rst に変更を加えてみて下さい。
sphinx-autobuild コマンドを実行したプロンプトでソースコードが変更されたことをきっかけにビルド処理が行われていることが確認でき、その後にブラウザが自動でリロードされることが確認できると思います。

sphinx-autobuild コマンドを実行することで自動でビルドすることが出来るようになりましたが、この設定を pipenv のスクリプトとして登録しておくことにします。
すると、 pipenv run auto_build 等、任意のコマンド名で pipenv run sphinx-autobuild source build を実行した時と同じ処理が行えるようになります。

ついでに build コマンドも登録しておきましょう。

Pipfile

  : <snip>
[scripts]
build = "sphinx-build -M html source build"
auto_build = "sphinx-autobuild -b html source build/html"

設定が終わったら pipenv run build や pipenv run auto_build が実行できるようになっていることを確認してみて下さい。

国際化(i18n)

作成したドキュメントの国際化(以降、i18n)を行います。

Sphinx における i18n の方法は Sphinx / 国際化を参考にします。

参照先の図に書かれているとおり、i18n に必要なファイルとして次のものがあります。

拡張子	説明
`.pot`	カタログテンプレートと呼ばれ、翻訳対象となる文字列が記載される。 `.rst`から作成される。コマンド sphinx-build gettext により作成される。
`.po`	メッセージカタログと呼ばれ、翻訳対象となる文字列とその訳語が記載される。 `.pot`から作成される。コマンド sphinx-intl により作成・更新される。
`.mo`	バイナリカタログと呼ばれ、メッセージカタログがバイナリで記載される。ビルド結果(HTML等)の元データとして利用されます

POファイルのフォーマット※

white-space
#  translator-comments
#. extracted-comments
#: reference…
#, flag…
#| msgid previous-untranslated-string
msgid untranslated-string
msgstr translated-string

※ POファイルのフォーマット https://www.gnu.org/software/gettext/manual/gettext.html#PO-Files

上記に記載したとおり .po ファイルは sphinx-intl コマンドで作成することが出来ます。

sphinx-intl は Python パッケージなので pipenv コマンドでインストールできます。

$ pipenv install --dev sphinx-intl

試しに index.rst ファイル内の Welcome to sphinx-doc-sample's documentation! を日本語にしてみることにします。

まずはソースコード内の翻訳対象の文字列を .pot ファイルに収集します。

$ pipenv run sphinx-build -M gettext source build

実行すると build/gettext/index.pot ファイルが作成されます。

build/gettext/index.pot

  : <snip>
#: ../../source/index.rst:7
msgid "Welcome to sphinx-doc-sample's documentation!"
msgstr ""
  : <snip>

次に .po ファイルを作成します。

$ pipenv run sphinx-intl update -d source/locales -p build/gettext -l ja

実行すると source/locales/ja/LC_MESSAGES/index.po が作成されます。
これを編集して日本語訳を記載してみましょう。

source/locales/ja/LC_MESSAGES/index.po

  : <snip>
#: ../../source/index.rst:7
msgid "Welcome to sphinx-doc-sample's documentation!"
msgstr "ようこそsphinx-doc-sampleドキュメントへ！"
  : <snip>

最後に language=ja を設定して HTML をビルドします。

$ pipenv run sphinx-build -M html source build -D language=ja

ビルドされた HTML を見ると日本語に翻訳されていることが分かると思います。

HTML をビルドするまでの一連のコマンドを pipenv のスクリプトとして登録しておくことにします。

Pipfile

  : <snip>
[scripts]
build = "sphinx-build -M html source build"
build_ja = "pipenv run build -D language=ja"
auto_build = "sphinx-autobuild -b html source build/html"
i18n_pot = "sphinx-build -M gettext source build"
i18n_po = "sphinx-intl update -d source/locales -p build/gettext -l ja"

1回のコマンド実行が楽になりましたが、やはりソースコードに変更があった場合に自動でビルドされるようにしたいものです。

一連の流れから分かるように .po ファイルまで作成されれば翻訳された HTML ファイルが作成できます。そこで HTML ファイルの自動ビルドは sphinx-autobuild に任せ、.rst -> .pot -> .po を自動で作成するスクリプトを定義してみたいと思います。

用途に適した Python パッケージが見付からなかったので、sphinx-autobuild でも利用している watchdog を使って自作することにします。

まずは watchdog をインストールし、Pipfile に watchdog パッケージをインストールすると使える watchmedo コマンドをスクリプトとして auto_i18n_po を登録します。

$ pipenv install --dev watchdog

Pipfile

[scripts]
build = "sphinx-build -M html source build"
build_ja = "pipenv run build -D language=ja"
auto_build = "sphinx-autobuild -b html source build/html"
auto_build_ja = "pipenv run auto_build -D language=ja"
i18n_pot = "sphinx-build -M gettext source build"
i18n_po = "sphinx-intl update -d source/locales -p build/gettext -l ja"
auto_i18n_po = "watchmedo shell-command --pattern='*.rst' --recursive --command='pipenv run i18n_pot && pipenv run i18n_po'"

これで、ターミナルを2つ用意して pipenv run auto_build_ja と pipenv run auto_i18n_po を実行することで翻訳環境においても自動でビルドされるようになります。

編集する流れとしては .rst ファイルを編集したら auto_i18n_po により .po ファイルが自動で作成・変更されるため、次に .po ファイルに訳語を記述すると auto_build_ja により自動で HTML が作成されるいう流れになります。

CI環境

定期的に Sphinx のドキュメントが正しいことをチェックする CI 環境を作っていこうと思います。

テストする内容を考える

最低限は各言語の HTML ファイルがビルド出来る必要があると思います。

次に Sphinx 開発環境における異常な状態について考えてみます。

翻訳対象の文字列が判別できていない
- メッセージカタログ(.po ファイル)に曖昧(Fuzzy)な対象が存在する
訳語が書かれていない
- メッセージカタログ(.po ファイル)のmsgstrが空である
メッセージカタログが正しく運用されていない
- メッセージカタログ(.po ファイル)のヘッダに翻訳した日付や翻訳者等の情報が記載されていない

上記を確認するために gettext ツールに含まれる msgfmt コマンドが利用できます。

msgfmt コマンドのオプションでそれぞれ確認できます。

--statistics
- 翻訳対象の文字列が判別できていない
- 訳語が書かれていない
-c, --check
- メッセージカタログが正しく運用されていない

msgfmtのヘルプ(抜粋)

Input file interpretation:
  -c, --check                 perform all the checks implied by
                                --check-format, --check-header, --check-domain
      --check-format          check language dependent format strings
      --check-header          verify presence and contents of the header entry
      --check-domain          check for conflicts between domain directives
                                and the --output-file option

Informative output:
      --statistics            print statistics about translations

翻訳作業を複数人で行っていて、メッセージカタログが正しく運用している状態を維持したい場合は、メッセージカタログのヘッダをチェックするとよいでしょう。
本記事では翻訳が正しく書かれているかどうかだけチェックすることにします。

CI環境を構築する

CI環境はリポジトリとして使っている GitHub の機能である Action を使ってみようと思います。

環境の構築方法は簡単で .github/workflows/*.yml ファイルを作るだけです。
Action の使い方の詳細は https://help.github.com/en/articles/workflow-syntax-for-github-actions を参照してください。

github/workflows/build_and_test.yml

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Set up Python 3.7
      uses: actions/setup-python@v1
      with:
        python-version: 3.7
    - name: Install dependencies
      run: |
        sudo apt-get install -y gettext
        python -m pip install --upgrade pip
        pip install pipenv
        pipenv sync --dev
    - name: Build
      run: |
        pipenv run build -W
        pipenv run build_ja -W
    - name: Test
      run: |
        STATISTICS_CMD="msgfmt -o /dev/null source/locales/ja/LC_MESSAGES/*.po -v --statistics"
        # Fail and show result if statistics of translation file include messages after 'translated messages'.
        #   invalid ex. source/locales/ja/LC_MESSAGES/index.po: 4 translated messages, 1 fuzzy translation, 1 untranslated message.
        $STATISTICS_CMD 2>&1 | grep -v -q ' translated messages, *' || ($STATISTICS_CMD && false)

これで新しい commit が push されたタイミングで Sphinx で正しく翻訳できることが確認できるようになります。
必要に応じて Pull Request が merge できる条件として、この Action が success になることを確認するよう設定するとよいと思います。

Sphinx 環境の構築 (poetry版)

poetry をインストールして仮想環境を構築する

poetry をインストールします。 (参考)

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python

pyproject.toml を作成します。
poetry init コマンドを実行するとインタラクティブモードになり、パッケージの説明やライセンス入力を行った後に、依存する PyPI パッケージを指定することになります。(依存する PyPI パッケージは後に手動で設定することも可能です)

$ poetry init

pyproject.toml

[tool.poetry]
name = "sphinx-doc-sample"
version = "0.1.0"
description = "Sample of sphinx document"
authors = ["tatsurou313"]

[tool.poetry.dependencies]
python = "^3.7"
sphinx = "^3.0.3"
sphinx-rtd-theme = "^0.4.3"

[tool.poetry.dev-dependencies]
sphinx-autobuild = "^0.7.1"
sphinx-intl = "^2.0.0"
watchdog = "^0.10.1"

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

次に poetry の挙動を設定します。

virtualenvをプロジェクトディレクトリ配下に作成する設定(poetry.toml)

[virtualenvs]
create = true
in-project = true

依存するパッケージをインストールする

依存する PyPI パッケージをインストールします。

$ poetry install

その他の設定

その他は pipenv を参考にして環境を構築します。

備考

virtualenv による仮想環境について

virtualenv による仮想環境は、環境下で使用する Python の実行ファイルと Python パッケージをコピーすることで隔離する仕組みのようです。(ファイル構成からの推測)

仮想環境の作成方法

virtualenv -p pythonX.Y ＜ENV_NAME＞

Running virtualenv with interpreter /usr/bin/python3.6
Using base prefix '/usr'
New python executable in /home/vagrant/work/virtualenv/p3.6/bin/python3.6
Also creating executable in /home/vagrant/work/virtualenv/p3.6/bin/python
Installing setuptools, pkg_resources, pip, wheel...done.

仮想環境配下に bin, lib/site-packages が存在します。
bin 配下には virtualenv の仮想環境を有効化する activate コマンドや python コマンドファイルがコピー又はシンボリックリンクが作成されます。

仮想環境は有効化(activate) する必要があります。

activate された仮想環境にて pip コマンドでインストールした Python パッケージは site-packages 配下にインストールされます。

pyenv コマンドリファレンス

インストールできる Python 一覧を表示する

pyenv install --list

Python をインストールする

pyenv install X.Y.Z  # X.Y.ZにPythonバージョンを指定する

インストールされている Python 一覧を表示する

pyenv versions

グローバルで利用する Python バージョンを指定する

pyenv global X.Y.Z  # X.Y.ZにPythonバージョンを指定する

ローカル(カレントディレクトリ)で利用する Python バージョンを指定する

pyenv local X.Y.Z  # X.Y.ZにPythonバージョンを指定する

pipenv について

仮想環境について

pipenv は virtualenv を利用しているため、pipenv による仮想環境は、virtualenv と同じ仕組みです。

仮想環境の作成

pipenv --python X.Y  # X.YはPythonバージョンを指定する

仮想環境はdefaultで以下のディレクトリに作成されます。

Windowsの場合
- %HOMEPATH%\.virtualenvs\＜ディレクトリ名＞-＜ハッシュ値？＞
Linux系OS, Mac OS
- $HOME/.local/share/virtualenvs/＜ディレクトリ名＞-＜ハッシュ値？＞

パッケージ管理について

Pipfile, Pipfile.lock ファイルを使ってパッケージの依存関係を管理します。

Pipfile の中にはセクションが分かれています。参照

[[source]]
[dev-packages]
[packages]
[requires]
他

[[source]] / [packages],[dev-packages] には主となる Python パッケージのリストがバージョンと一緒に書かれます。

[[source]]
  : <snip>
[packages]
sphinx = "*"
  : <snip>

バージョンは Semantic Versioning scheme に従って指定します。

[dev-packages] には pipenv コマンドで --dev オプションを付けた時だけインストールできるパッケージを指定でき、開発環境でのみ必要なパッケージを指定する場合に使えます。

pipenv コマンドは [packages] と [dev-packages] に書かれた Python パッケージと、そのパッケージが依存するパッケージを Pipfile.lock にバージョンと共に書き出します。

Pipfile.lockの構造

{
    "_meta": {
        "hash": {
            "sha256": "7ae784320bc5cb9bf2d678b7069adb456313812afb07931a29d78352dc75f63e"
        },
        "pipfile-spec": 6,
        "requires": {
            "python_version": "3.5"
        },
        "sources": [
            {
                "name": "pypi",
                "url": "https://pypi.org/simple",
                "verify_ssl": true
            }
        ]
    },
    "default": {
        "alabaster": {
            "hashes": [
                "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
                "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"
            ],
            "version": "==0.7.12"
        },
          : <snip>
        "sphinx": {
            "hashes": [
                "sha256:22538e1bbe62b407cf5a8aabe1bb15848aa66bb79559f42f5202bbce6b757a69",
                "sha256:f9a79e746b87921cabc3baa375199c6076d1270cee53915dbd24fdbeaaacc427"
            ],
            "index": "pypi",
            "version": "==2.1.2"
        },
          : <snip>
    },
    "develop": {}
}

パッケージのインストール

Pipfile, Pipfile.lock ファイルがあれば pipenv コマンドを使って開発環境を再構築することが出来ます。

複数人で同じ Python のプロジェクトを開発する場合等に開発環境を構築する必要があり、ソースコードリポジトリに Pipfile, Pipfile.lock が存在してそれらのファイルがコピーされていることを前提とします。

開発環境を再構築する(Pipfile,Pipfile.lockを含むソースコードから開発環境を構築する)

$ cd ＜Pipfile,Pipfile.lockがあるディレクトリ＞
$ pipenv sync [--dev]  # --devオプションは必要に応じて設定する

パッケージのアップデート

Pipfile に書かれたバージョンの範囲でパッケージをアップデートし、Pipfile.lock も更新されます。

$ pipenv install

Sphinxによるドキュメント作成と国際化の事始め

本記事について

技術スタックについて

Sphinx とは

Sphinx 環境の構築 (pipenv版)

Python とパッケージの実行環境について

Python 実行環境を構築する

pipenv をインストールして仮想環境を構築する

Sphinx パッケージをインストールする

Sphinx を初期化してHTMLドキュメントを作成する

ソースコードとビルドスクリプトを作成する

HTML をビルドしてみる

Sphinx にテーマを適用する

ビルド環境を改善する

sphinx-autobuild をインストールする

国際化(i18n)

CI環境

テストする内容を考える

CI環境を構築する

Sphinx 環境の構築 (poetry版)

poetry をインストールして仮想環境を構築する

依存するパッケージをインストールする

その他の設定

備考

virtualenv による仮想環境について

pyenv コマンドリファレンス

インストールできる Python 一覧を表示する

Python をインストールする

インストールされている Python 一覧を表示する

グローバルで利用する Python バージョンを指定する

ローカル(カレントディレクトリ)で利用する Python バージョンを指定する

pipenv について

仮想環境について

パッケージ管理について

パッケージのインストール

パッケージのアップデート