【Python】MkDocsを利用したDocumentation用の静的サイト構築

Argo のようなおしゃれなDocを作ってみたいということでMaterial for MkDocsをローカルで作って触ってみたので、セッティングとかの備忘録がてら記事にしたいと思います。

実行環境

実行環境 - pyenv + pyenv-virtualenv
Python Version - python 3.8.0

pyenv + pyenv-virtualenv で実行環境設定

既存の環境は汚したくないので新しいpython仮想環境を新規作成して、その上で実行するようにします。

# python ver インストール
pyenv install 3.8.0
pyenv versions 

# 仮想環境sample-mkdocsの作成
pyenv virtualenv 3.8.0 sample-mkdocs
pyenv versions 

# ローカルに適用
cd /path/to/sample-mkdocs
pyenv local sample-mkdocs

# 確認(versionが3.8.0)
python -V

mkdocs インストール

https://www.mkdocs.org/getting-started/ の通りにmkdocsをインストールする。

さらに、materialテーマを利用するため、https://squidfunk.github.io/mkdocs-material/getting-started/ を参考にmkdocs-materialをインストール。

上記を実行した結果、pip freezeの結果は以下の通り。もし不足パッケージがある場合は適宜インストールをお願いします。

click==8.0.1
ghp-import==2.0.1
importlib-metadata==4.6.0
Jinja2==3.0.1
Markdown==3.3.4
MarkupSafe==2.0.1
mergedeep==1.3.4
mkdocs==1.2.1
mkdocs-material==7.1.9
mkdocs-material-extensions==1.0.1
packaging==20.9
Pygments==2.9.0
pymdown-extensions==8.2
pyparsing==2.4.7
python-dateutil==2.8.1
PyYAML==5.4.1
pyyaml-env-tag==0.1
six==1.16.0
watchdog==2.1.3
zipp==3.4.1

Verを合わせたい場合は、上記の内容をrequirements.txtに出力してインストール。

cat <<EOF > requirements.txt
  :
上記内容
  :
EOF

# install 
pip install -r requirements.txt
# confirm
pip freeze

mkdocs.ymlの編集

mkdocs.ymlを編集することで、コードハイライトやナビゲーションバーの表示等細かいレイアウトが可能になります。一つ一つ解説するのは面倒なので、なるべくコメントにのこしました。小一時間触った結果、良さげな感じに仕上がったのでその時のmkdocs.ymlは以下のようになります。

site_name: hogehoge's Docs
site_url: https://example.com/

docs_dir: "docs"

theme:
  name: material
  locale: ja
  language: ja # メニュー言語を日本語に変更.
  features:
    - search.suggest # Search suggestions
    - navigation.tabs
    - navigation.expand
    - navigation.top
  palette:
    - scheme: default # slate
      primary: light blue
      toggle:
        icon: material/weather-sunny
        name: "ダークモードに切り替え / Switch to dark mode"
    - scheme: slate
      primary: red
      toggle:
        icon: material/weather-night
        name: "ライトモードに切り替え / Switch to light mode"

plugins:
  - search:
      min_search_length: 100 # 検索文字数上限. エラー文も含めたい
      separator: '[\s\-\.]+'  # 検索単語の区切り文字
      lang: ja  # 言語

markdown_extensions:
  - admonition
  - def_list
  - toc:
      permalink: true   # リンク
      slugify: !!python/name:pymdownx.slugs.uslugify_cased  # 日本語をリンクにふくめる場合設定
  - pymdownx.highlight: # ハイライト
      linenums: true # 行番号
      noclasses: true # インラインスタイル
      linenums_style: pymdownx-inline
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid # https://github.com/squidfunk/mkdocs-material/issues/693
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_div_format
  - pymdownx.details # コンテンツの折り畳み
  - pymdownx.inlinehilite # コードハイライト
  - pymdownx.snippets 
  - pymdownx.keys # キーボードキーの表示 ++文字++

extra_css:
  - https://unpkg.com/mermaid@7.1.2/dist/mermaid.css  # mermaid
extra_javascript:
  - https://unpkg.com/mermaid@7.1.2/dist/mermaid.min.js # mermaid

# Copyright
copyright: "hogehoge © 2021 " # footer copyright

# navigation 
nav:
  - はじめに: index.md
  - About: about.md
  - AWS:
      - Home: aws.md
      - TL;DR: aws/aws_tldr.md
      - Certification:
          - AWS_SAP: aws/certification/aws_certifications.md
      - Models:
          - WebApplicatin:
              - 3Tiers: aws/models/webapp/aws_webapp_3tiers.md
          - Serverless:
              - SinglePageApplication: aws/models/serverless/aws_serverless_spa.md

フォルダ構成

上記 mkdocs.yml の nav のようなmdファイルを用意してあげ、navに追加するだけで反映されます。今回は下記のように階層を深くしても、navの修正のみですむため、コーディングなしで設定反映でき、インフラ屋の私でもカジュアルに変更を加えられるので、超便利です。

sample-mkdocs/
├── docs/
│   ├── aws/
│   │   ├── certification/
│   │   │   └── aws_certifications.md
│   │   └── models/
│   │       ├── serverless/
│   │       │   └── aws_serverless.md
│   │       └── webapp/
│   │           └── aws_webapp_3tiers.md
│   ├── img/
│   │   └── aws/
│   │       └── sample.png

まとめ

最初はDjangoで作ろうかと考えていたのですが、MkDocs で簡単にセットアップできました。クラウド上でデプロイするためのアーキテクチャについても今後作成していこうと思います。

猫キック

IT関連について投稿