BitbucketPipelinesを使ってMkDocsのMarkdown形式のファイルをPDFにする

# 概要

[Bitbucket](https://bitbucket.org/)のCIツールとしては`Bitbucket Pipelines`が提供されている。
`GithubActions`同様に`artifacts`と呼ばれる成果物というかビルド産物を生成・ダウンロードすることができるので[MkDocs](https://www.mkdocs.org/)のビルドプロセスをパイプラインに流し込んでMarkdownをPDFに変換してみる。

レポジトリは[こちら](https://bitbucket.org/higebobo/mkdocs-sample/)

# 環境

* Linux Mint 19.1 Tessa
* Python-3.9.1

# 準備

ライブラリのインストール

```shell
pip install -r requirements.txt
```

requirements.txt

```
mkdocs==1.2.1
mkdocs-with-pdf==0.9.3
mkdocs-material==7.1.9
qrcode==7.1
WeasyPrint==52.5
```
2021年8月13日現在、`WeasyPrint`の最新版である53.0は`Pango>=1.44`を要求する。
そのため`mkdocs-with-pdf`の依存関係で自動的にインストールされるが上記環境を満たしていない場合は、明示的にバージョンを指定しなければならない。

[v53\.0b2 Global Installation · Issue \#1384 · Kozea/WeasyPrint](https://github.com/Kozea/WeasyPrint/issues/1384)

`qrcode`はバックカバーを出力する場合に必要で`mkdocs-material`は好みの問題で使用(PDF出力には関係ない)。

# プロジェクト作成

`MkDocs`のプロジェクトを作成する。

```shell
mkdocs new sample
cd sample
```
# ローカルレポジトリの作成

一旦、ここでBitbucketのレポジトリを作成する。
まずローカル環境での`Git`の初期化(`.gitignore`は好みで)

```shell
git init
echo "# README" > README.md
echo '*~' >> .gitignore
echo '*.bak' >> .gitignore
echo '*.orig' >> .gitignore
echo '.env' >> .gitignore
echo '*.pyc' >> .gitignore
echo '__pycache__' >> .gitignore
echo '.python-version' >> .gitignore
echo 'site' >> .gitignore
```

コミット(ブランチ名の変更は一応Githubの流儀に合わせた)

```shell
git add .
git commit -m 'first commit'
git branch -M main
```

# リモートレポジトリの作成

ここまでできたら`Bitbucket`のレポジトリを作成する。

ダッシュボード>左上`+`マークの`Create`>`Repository`から作成。
私の場合はこんな感じの設定にした。

![FireShot Capture 056 - Create a repository — Bitbucket - bitbucket.org.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/691494/8812176e-62cb-6e3e-e3d5-74ace79183e2.png)

そしてリモートレポジトリにプッシュする。

```
git remote add origin git@bitbucket.org:<youraccount>/mkdocs-sample.git
git push -u origin main
```

# 文書作成

準備が完了したので文書を作成する。`docs/index.md`を適当に編集する。

`docs/index.md`

```markdown
# MkDocsへようこそ

ドキュメントのすべてはこちらをご覧ください。 [mkdocs.org](https://www.mkdocs.org).
...
```

設定ファイルの編集

`docs/mkdocs.yml`

```yaml
site_name: サンプルドキュメント
site_url: http://localhost:8000
repo_url: https://bitbucket.org/<youraccount>/mkdocs-sample/

nav:
    - はじめに: 'index.md'

plugins:
    - search
    - with-pdf:
        author: youraccount
        copyright: youraccount

        # cover: false
        # back_cover: false
        cover_title: サンプルドキュメント
        cover_subtitle: MkDocsによる技術文書
        toc_title: 目次
        # verbose: true

theme:
  name: material
  language: ja

extra:
  search:
    language: ja

markdown_extensions:
    - admonition
```

# サービス起動およびビルド

文章ができたらローカル環境でサービスを起動する。

```shell
mkdocs serve
```

`http://localhost:8000`にアクセスするとこんな感じ。
`repo_url`を指定しているためリモートレポジトリのリンクが参照できている。

![FireShot Capture 057 - サンプルドキュメント - localhost.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/691494/f9481a91-692e-42c4-ee50-d2dbb81019e2.png)

次にビルドを行う。ここでhtmlとpdfが生成される。

```shell
mkdocs build
```

# Bitbucket Pipelinesへの流し込み

`MkDocs`のビルドができることが確認できればパイプラインの設定を行う。
ローカルプロジェクト配下に以下を作成。

`bitbucket-pipelines.yml`

```yaml
image: python:3.9.6-slim-buster

pipelines:
  default:
    - step:
        name: Build Document
        caches:
          - pip
        script:
          - apt update
          - apt -y install wget libcairo2 libgtk-3-0 xz-utils
          - wget https://osdn.net/dl/mplus-fonts/mplus-TESTFLIGHT-063a.tar.xz
          - tar xvfJ mplus-TESTFLIGHT-063a.tar.xz -C /usr/share/fonts
          - rm -rf mplus-TESTFLIGHT-063a.tar.xz
          - pip install -U pip
          - pip install -r requirements.txt
          - mkdocs build
          - mv site/pdf/document.pdf .
        artifacts:
          - document.pdf
```

作成したらコミット＆リモートにプッシュ。
その後、Bitbucketのレポジトリのダッシュボード>`Pipelines`>`Enable pipeline`をクリックする。
そうすると`CI`が動き始める。

![FireShot Capture 058 - higebobo _ mkdocs-sample _ Pipelines — Bitbucket - bitbucket.org.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/691494/313ff838-dde6-0d8c-0606-3a3210363d13.png)

無事完了すると`Artifacs`のボタンが表示される。

![FireShot Capture 059 - higebobo _ mkdocs-sample _ Pipelines — Bitbucket - bitbucket.org.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/691494/3492de74-5168-e474-6cdd-e773af88c5e5.png)

右にダウンロードボタンがあるのでそれをクリックしてローカルに保存して解答するとPDFができている。

![Screenshot at 2021-08-13 10-31-31.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/691494/b2f97fa5-319e-95b7-7791-9824bad282d8.png)


# まとめ

作業そのものは簡単だが日本語を表示するのにひと工夫いる(参考:[WeasyPrintでPDF出力するまでの環境構築\(Django/Amazon Linux\) \- qtatsuの週報](https://qtatsu.hatenablog.com/entry/2020/08/10/200610#%E6%96%87%E5%AD%97%E5%8C%96%E3%81%91%E3%81%B8%E3%81%AE%E5%AF%BE%E5%BF%9C))。

Github Pagesのように静的コンテンツを提供する仕組みがあるのでpdf出力と合わせて生成されたhtmlを公開することもできるが今回は割愛する。
Github Actionsに比べ情報が少ないため参考になれば幸いである。