MkDocs+GitLab-CI+wkhtmltopdf でドキュメント更新作業の煩雑さから解き放たれる

2019年1月25日 18:05

マニュアルの管理運用をやってるのですが、WORD だったり PPT だったり Sphinx だったりで作った資料をGドライブに格納して社外向けに配るときは PDF を zip してパスかけて BOX にあげて共有用 URL をメールで送って、解凍パスワードを別送するとかもう嫌だ！と思ったので、これからのスタンダードはこれにすると決めたときにやったこと。

🍄 前提

Windows 利用者向け

🍄 MkDocs を使える環境を整える

MkDocs は markdown 形式で簡単にドキュメントが作成できるツール。無料です。

python がいります。2.x 系でも 3.x 系でも。なければインストールを。

$ python --version
Python 2.7.12

pip で mkdocs をインストールするので、存在しているか確認。

$ pip --version
pip 9.0.1 from /usr/local/lib/python2.7/dist-packages (python 2.7)

🍄 MkDocs をインストール

$ pip install mkdocs-material

これだけ。すぎょい。バージョン確認しておきせう。

$ mkdocs --version
mkdocs, version 0.17.2

完了。

🍄ドキュメントを作成

よき場所に移動して、以下のコマンドを入力。

$ mkdocs new dashbordDocs

作成されたフォルダ名に移動して mkdocs serve します。

$ cd dashbordDocs
$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 190125 15:32:00 server:283] Serving on http://127.0.0.1:8000
[I 190125 15:32:00 handlers:60] Start watching changes
[I 190125 15:32:00 handlers:62] Start detecting changes
[I 190125 15:32:18 handlers:133] Browser Connected: http://127.0.0.1:8000/

この状態で以下のURLにアクセスすると、リアルタイムで確認できます。
http://127.0.0.1:8000/

こんな感じ。

🍄 設定ファイルの変更

レイアウトや、拡張機能の設定ができます。

site_name: サイト名
pages:
- Home: 'index.md'
- セットアップ:
 - '環境情報': 'setup/setup.md'

# Copyright
copyright: 'Copyright (c) xxxx 2019'
theme:
 docs_dir: 'docs'
 name: 'material'
 language: 'ja'
 palette:
   primary: 'Teal'
   accent: 'Teal'
 feature:
   tabs: true
 logo:
  icon: 'send'
extra:
search:
 language: 'jp'
 font:
     text: 'Roboto'
     code: 'Roboto Mono'
markdown_extensions:
- admonition
- toc:
   permalink: 'true'
- pymdownx.emoji     <!-- 絵文字を使いたい -->
use_directory_urls: false

マテリアルテンプレートがおすすめらしいけど、他にもいろいろ。

🍄ドキュメントの追加・編集など

こちらの記事がまとまってて分かりやすい。

🌈 GitLab-CI で自動化

MkDocsで作成したドキュメントを HTML化して、web上にあげたい。メールでなんて送りたくないから。ということで、AWS の S3 （静的ウェブサイトホスティング機能）にアップロードします。

更新する度にアップロードするのは面倒なため、GitLab-CI で gitlab のマスターに修正がマージされた時点で、一連の流れを自動で実行したい。

.gitlab-ci.yml というファイルをリポジトリのルートに置くだけでCIを実現できます。下準備＆設定はエンジニアのひとがやってくれた。ありがとうありがとう🙏

🌈 中身はこんな感じ。あとで説明を追記したいところ。

image: python:3.6

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - pip install mkdocs
    - pip install mkdocs-material
    - cd ./dashboad-docs/
    - mkdocs build -d public
  artifacts:
    paths:
      - public
  only:
    - master

deploy:
  stage: deploy
  script:
    - pip install mkdocs
    - pip install mkdocs-material
    - pip install awscli
    - cd ./dashboad-docs/
    - mkdocs build -d public
    - aws s3 sync ./public s3://${S3_BUCKET_NAME}/${PREFIX}
  only:
    - master

これで完了💪

なのだが、今までは PDF で配布していたため、念のためそのあたりの懸念もつぶしておきたい。HTML -> PDF 変換ツールを探したところ wkhtmltopdf てツールがよさげ。

💡 wkhtmltopdf のインストール

$ sudo apt-get install wkhtmltopdf

バージョン確認

$ wkhtmltoimage --version
wkhtmltoimage 0.12.2.4

$ wkhtmltopdf --version
wkhtmltopdf 0.12.2.4

完了。ただ、このままだと変換したときに日本語が豆腐になってしまうため、フォントインストールする。

📛 IPAフォントインストール

ググると大抵この方法を推奨しているため、おとなしく従います。

$ wget http://dl.ipafont.ipa.go.jp/IPAexfont/IPAexfont00301.zip
$ unzip IPAexfont00301.zip 
$ sudo mv IPAexfont00301 /usr/share/fonts
$ fc-cache -fv

zipのリンクが死んでたら以下サイトで最新verをお確かめください。

💡 PDF 出力

URLを指定してPDFに変換

 wkhtmltopdf http://www.xxxxx.co.jp XXXX.pdf

ローカルの html ファイルを変換

wkhtmltopdf input.html output.pdf

MkDocs を build すると site フォルダに HTML ができるので、HTML指定でもPDF変換できます。

ちょっと途中で切れたりしてしまうので、プリント用の CSS を指定するといいそうですが、今から全体会議なので一旦これで公開 🐥