コンテンツにスキップ

動作確認

環境構築 でみてきた通り、以下を使用する前提で動作確認していきます:

  1. PyCharm Community Edition
  2. GitHub

git clone からプロジェクト作成

ここでは仮に GitHub リポジトリ URL を https://github.com/kojion/chess.git としておきます。 ローカルディレクトリの好きな場所で git clone https://github.com/kojion/chess.git を実行してください。 PyCharm を使用している場合はユーザディレクトリ直下に PyCharmProjects ができているはずなので、そこに cd してから git clone されると良いでしょう。 GitHub リポジトリにデフォルトで入っている README.md や LICENSE1 が落ちてきたはずです。 そこで以下を実行します:

cd ../
mkdocs new (clone したリポジトリ名)

これで clone したリポジトリ名のディレクトリに対して MkDocs の初期ファイル2が生成されます。

PyCharm のプロジェクト設定ファイル .idea について

PyCharm でプロジェクトとして開いて操作している場合 .idea というディレクトリが自動生成されプロジェクトの設定ファイルが格納されます。 しかしこれはソースコード上は不要なファイル群ですので .gitignore を用意して .idea を除外しておくことをお勧めします。

まずは動作確認を行いたいので、とりあえずこれで push してみましょう。 PyCharm 上でディレクトリを右クリックして Git -> ディレクトリのコミット を選択し、コミットとプッシュを選択します。 push が成功したらそのようなメッセージが表示され GitHub のリポジトリサイトを見てみるとソースコードが上がっているはずです。

ローカル環境での確認

まずこのままで動作確認をしてみましょう。 ターミナルで mkdocs serve と叩いてください。 そうすると成功時には以下のように表示されます:

PS C:\Users\kojion\PycharmProjects\chess> mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.56 seconds
INFO     -  [16:20:54] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [16:20:54] Serving on http://127.0.0.1:8000/chess/

表示された内容に従い http://127.0.0.1:8000/chess/ にアクセスしてみてください3。 初期状態は割と味気ない感じの画面ですが、確かに docs/index.md から生成されたであろう Web サイトが表示されるはずです。 この mkdocs serve はいわゆる ホットデプロイ となっておりますので、そのまま index.md を適当に書き換えてみてください。 変更した Markdown ソースが即座に Web サイトに反映されて表示が確認できます。 MkDocs はこれがとても便利です。

HTML 生成

GitHub にデプロイする場合は必要ない作業

後述する GitHub Pages にデプロイする場合はこちら側で HTML ファイルを生成する必要はありませんが、レンタルサーバなどに配置することを踏まえて念のため触れておきます。

mkdocs build を叩くことで site ディレクトリが生成され、そこに mkdocs serve でみてきた Web サイト相当の HTML ファイルが生成されます。 レンタルサーバなどに配置する際は、この site ディレクトリ以下を FTP ないし SCP でコピーするか、若しくはサーバ側で適宜 git pull して得たソースコード内の site を DocumentRoot として設定するとよいでしょう。

GitHub Pages へのデプロイ

これがびっくりするほど簡単で初めて見たとき感動すると思います。 mkdocs gh-deploy を叩くだけです。 そうするとコンソールに以下のように表示されます:

PS C:\Users\kojion\PycharmProjects\chess> mkdocs gh-deploy
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: C:\Users\kojion\PycharmProjects\chess\site
INFO     -  Copying 'C:\Users\kojion\PycharmProjects\chess\site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 36, done.
Counting objects: 100% (36/36), done.
Delta compression using up to 16 threads
Compressing objects: 100% (19/19), done.
INFO     -  Documentation built in 0.64 seconds
INFO     -  Copying 'C:\Users\kojion\PycharmProjects\chess\site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 26, done.
Counting objects: 100% (26/26), done.
Delta compression using up to 16 threads
Compressing objects: 100% (13/13), done.
Writing objects: 100% (14/14), 8.39 KiB | 2.10 MiB/s, done.
Total 14 (delta 8), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (8/8), completed with 7 local objects.
To https://github.com/kojion/chess.git
   d515654..cfa4bce  gh-pages -> gh-pages
INFO     -  Your documentation should shortly be available at: https://kojion.github.io/chess/

メッセージの通り GitHub の main ブランチではなく gh-pages にプッシュされ、それが GitHub Pages として反映されます。 表示された URL にアクセスすることで、正しくデプロイされたことが確認できます。

  1. リポジトリ作成時にライセンスを選択すると生成される ↩

  2. mkdocs.yml と docs/index.md ↩

  3. PyCharm のターミナル上であればリンクになっているのでクリックするだけです ↩

コメント