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

10328 ワード
BitbucketPipelines MkDocs MkDocs テキストリンク

概要

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

レポジトリはこちら

環境

  • Linux Mint 19.1 Tessa
  • Python-3.9.1

準備

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

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

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

プロジェクト作成

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

mkdocs new sample
cd sample

ローカルレポジトリの作成

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

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の流儀に合わせた)

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

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

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

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

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

git remote add origin [email protected]:<youraccount>/mkdocs-sample.git
git push -u origin main

文書作成

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

docs/index.md

# MkDocsへようこそ

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

設定ファイルの編集

docs/mkdocs.yml

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

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

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

mkdocs serve

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

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

mkdocs build

Bitbucket Pipelinesへの流し込み

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

bitbucket-pipelines.yml

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が動き始める。

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

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

まとめ

作業そのものは簡単だが日本語を表示するのにひと工夫いる(参考:WeasyPrintでPDF出力するまでの環境構築(Django/Amazon Linux) - qtatsuの週報)。

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