GitとSourceTreeでSphinxのドキュメントのバージョン管理をしてみる¶
Sphinxの原稿になるファイルはテキストファイルですので、バージョン管理システムを使って管理してみます。
Gitはそもそも分散してプロジェクト進行する場合のためのバージョン管理システムですが、サーバー不要なシステムなので、一人で使う場合でも単純なバージョン管理システムとして使えます。
Gitをビジュアルで使うツールとして、SourceTreeを使います。
Git for WindowsとSource Tree for Windowsのインストール¶
インストールの仕方は、他に詳しい解説サイトがありますので、そちらを参照してください。
Sphinxのドキュメントプロジェクトを作る¶
Sphinxのドキュメントを保存するフォルダを作ります。 そのフォルダで、
> sphinx-quickstart
して、ドキュメントのプロジェクトを作ります。 既存のドキュメントを管理するのであれば、この工程は不要ですね。
試しに、c:git_testというフォルダにgit_trialというプロジェクトを作ってみます。
> cd C:\git_test
> sphinx-quickstart
そうすると、下図のようにフォルダとファイルが作成されます。
SourceTreeでリポジトリを作る¶
SourceTreeを起動します。
「新規/クローンを作成する」→「リポジトリを作成」をクリックし、「保存先のパス」にC:git_testと入力します。右側の「・・・」をクリックすると、フォルダ選択のダイアログが開くので、それを使っても良いです。
そして「作成」をクリックすると、リポジトリが作られます。
この時点でC:git_testの下に.gitというフォルダが作られます。Gitの管理用のフォルダですね。
_buildを管理しないようにする¶
原稿やテンプレートや設定だけを管理すれば良いと思いますので、_buildフォルダを管理対象外にします。
SourceTreeの「操作」メニューの中の「無視・・・」を選択すると、無視する条件のダイアログが出ます。 何もしないで、そのまま「OK」をクリックします。
そうすると、.gitignoreというファイルが作られます。
このファイルに、管理しないフォルダを記入します。
バージョン管理しないファイルやフォルダをこのファイルに記入すると、SourceTreeに表示されなくなります。
バージョン管理を始める¶
ファイルをGitに登録します。コミットと言います。
ファイルステータスのタブを開くと、SourceTreeの画面に、C:git_testのファイルが表示されます。
このファイルのチェックボックスをクリックすると、「作業ツリーのファイル」から「Indexにステージしたファイル」にファイル名が移動します。
「コミット」メニューをクリックし、コメントを記入して、「コミット」ボタンをクリックします。
「ブランチ」の「master」をクリックすると、登録されたファイルが見えます。
フォルダは表示されません。例えば_templatesなどのフォルダ内にファイルを作ると、そのファイルが表示されます。
例えば、_templatesにlayout.htmlというファイルをつくると、SourceTreeの「ファイルステータス」タブに下図のようにフォルダパスが付いた状態でファイル名が表示されますので、必要に応じてコミットします。
ファイルを更新して登録する¶
ファイルを書き換えて、登録してみます。
intex.rstに、Hello, World!と記入します。
Welcome to git_trial's documentation!
=====================================
Contents:
.. toctree::
:maxdepth: 2
Hello World!
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
そして、HTMLで出力すると、こういうHTMLファイルが得られます。
> make html
SourceTreeで「master」ブランチをみると、「コミットされていない変更があります」と表示されます。そこをクリックすると、「作業ツリーのファイル」タブにindex.rstが表示され、その右側に変更内容が表示されます。
ファイルを登録したときの要領でindex.rstをコミットすると、変更が登録されます。
_buildの下位のフォルダにSphinxが生成したHTMLファイルがありますが、.gitignoreに_buildを無視するように書いてあるので、HTMLファイルはSourceTreeに出てきません。
コミットを取り消したりバラエティを作ったり¶
あとは、GitおよびSourceTreeの使い方になります。詳しいサイトがたくさんありますので、そちらを参照してください。