コンテンツにスキップ

Mkdocs Macro を利用した HTMLへの履歴表示の追加

test
「mkdocsの更新履歴を表示する」、を実現するにあたり、
様々な要素が必要となった。
リサーチにより、自己の知識の強化が行われたのでここに記します。
記事内には、いろいろ引用もさせて頂いている。

参考基となったサイト1 Andoさん(reincarnation_tech)


■はじめに

docsの各々のフォルダ以下に md ファイルを其々置いて、記事を書いて、Push することで、記事の更新ができるのは良いが、
いつ何を更新したかの更新履歴が無いと、色々不便である。
そこで、Githubのコミットログを使用して自動で履歴ページを作れるようにします。

その為には、
1. Githubへのアクセスが必要
また、
2. Pythonで書いたスクリプトの結果を記事に埋め込む事ができるプラグインを利用

2.については、プラグインを作らなくてもいろんなことができるようになるそうです。このマクロを使用して、あると便利なものを色々追加出来るそうだ。
そのひつとして、更新履歴表示がある。それを利用します。

参考基となったサイト2 Andoさん(mkdocsでTechサイトを作ろう)

更新履歴表示の実現にあたり、私の不足していた知識も明確になった。

●環境

  • windows10 pro
  • python3.7.7

●この度取得出来た、知識やテクニック

  • pythonファイル を利用した、Github(mkdocsを基とした履歴を含むHTMLファイルの置き場所)への、アクセス方法
  • pythonファイル を利用した、Mkdocsファイル(.md)の運用方法と、考え方
    (DCC app の Maya とは無関係であることが、今回大きなトピックでもあります)
  • GitPython のインストール
  • mkdocs-macros-plugin のインストール
  • IDE PyCharm を使用した、pythonファイル の、運用方法

では、以下手順を追って説明することで、履歴ページ表示が実現出来ます。


■手順

●pip install の準備

以下のインストールを必要とします。

  • Gitリポジトリの内容の取得 には

    Pythonモジュール GitPython

    Pythonモジュール GitPython とは?

    MkDocsのプラグインではなく、MkDocsの拡張機能(Extension)でもありません。
    MkDocsがGitリポジトリの内容を取得してサイトの構築や管理に使用するための依存関係です。
    GitPythonは、MkDocsがプロジェクトを管理するために使用する Pythonモジュール の1つです。

  • 更新履歴表示(macros) には

    MkDocsプラグイン mkdocs-macros-plugin

    MkDocsプラグイン mkdocs-macros-plugin とは?

    これはMkDocsのビルドプロセスに干渉して、マクロ機能を提供するためのものです。
    マクロプラグインは、MkDocsのプロジェクトにカスタム機能を追加し、ビルド時に特定の処理を行うための手段を提供します。

以上が、この度の目標実現の手段です。

さて、まず、windows ターミナルを起動し、以下を実行し、ユーザーの現状を確かめます。

  • pipで管理されたパッケージであれば、インストール済みパッケージ(plug-ins や拡張機能等のバージョン)一覧を確認

    pip list

    私の pip list
    C:\Users\●●●>pip list
    Package                                   Version
    ----------------------------------------- ----------
    appdirs                                   1.4.4
    astroid                                   2.15.8
    Babel                                     2.12.1
    bracex                                    2.3.post1
    certifi                                   2023.7.22
    charset-normalizer                        3.2.0
    click                                     8.1.7
    colorama                                  0.4.6
    dill                                      0.3.7
    docutils                                  0.20.1
    fissix                                    21.11.13
    fontawesome-markdown                      0.2.6
    future                                    0.18.3
    ghp-import                                2.1.0
    gitdb                                     4.0.10
    idna                                      3.4
    importlib-metadata                        6.7.0
    isort                                     5.11.5
    Jinja2                                    3.1.2
    lazy-object-proxy                         1.9.0
    Markdown                                  3.4.4
    MarkupSafe                                2.1.3
    mccabe                                    0.7.0
    mergedeep                                 1.3.4
    mkdocs                                    1.5.2
    mkdocs-awesome-pages-plugin               2.9.2
    mkdocs-git-revision-date-localized-plugin 1.2.0
    mkdocs-material                           9.2.7
    mkdocs-material-extensions                1.1.1
    modernize                                 0.8.0
    natsort                                   8.4.0
    packaging                                 23.1
    paginate                                  0.5.6
    pathspec                                  0.11.2
    pip                                       24.0
    pip-review                                1.3.0
    platformdirs                              4.0.0
    pyenchant                                 3.2.2
    Pygments                                  2.16.1
    pylint                                    2.17.7
    pymdown-extensions                        10.2.1
    pymel                                     1.4.0
    PySide2                                   5.15.2.1
    python-dateutil                           2.8.2
    pytz                                      2023.3
    PyYAML                                    6.0.1
    pyyaml_env_tag                            0.1
    regex                                     2022.10.31
    requests                                  2.31.0
    setuptools                                41.2.0
    shiboken2                                 5.15.2.1
    six                                       1.16.0
    smmap                                     5.0.0
    termcolor                                 2.3.0
    tomli                                     2.0.1
    tomlkit                                   0.12.3
    typed-ast                                 1.5.5
    typing_extensions                         4.7.1
    urllib3                                   2.0.4
    watchdog                                  3.0.0
    wcmatch                                   8.4.1
    wheel                                     0.42.0
    wrapt                                     1.16.0
    zipp                                      3.15.0
    
  • バージョンの一番高いpythonバージョンの出力

    python -V or python --version

    私の python -V
    C:\Users\●●●>python -V
    Python 3.7.7
    
  • pip自身のインストールされている場所を示す

    pip show pip

    私の pip show pip
    C:\Users\●●●>pip show pip
    Name: pip
    Version: 24.0
    Summary: The PyPA recommended tool for installing Python packages.
    Home-page:
    Author:
    Author-email: The pip developers <distutils-sig@python.org>
    License: MIT
    Location: c:\users\●●●\program\python377\lib\site-packages
    Requires:
    Required-by: pip-review
    
  • 実際のパス "c:\users\●●●\program\python377\lib\site-packages" を確認

  • 拡張機能 mkdocs-material のバージョンを調べる e.g.): mkdocs-material

    pip show mkdocs-material

    私の pip show mkdocs-material
    C:\Users\oki44>pip show mkdocs-material
    Name: mkdocs-material
    Version: 9.2.7
    Summary: Documentation that simply works
    Home-page:
    Author:
    Author-email: Martin Donath <martin.donath@squidfunk.com>
    License:
    Location: c:\users\●●●\program\python377\lib\site-packages
    Requires: babel, colorama, jinja2, markdown, mkdocs, mkdocs-material-extensions, paginate, pygments, pymdown-extensions, regex, requests
    Required-by:
    

どうやら、当該のPC内では、バージョンの一番高い最新のpythonは、python3.7.7 であることが判明します。
そして、
c:\users\●●●\program\python377\lib\site-packages に、
pip install *** で、過去実行されてきたものが入っていることが判明します。

以上で、確認が取れました。いざ、インストールを実行していきます。

●pip install を始める

  • Pythonモジュール GitPython のinstall
    Gitリポジトリの内容の取得

    pip install GitPython

  • MkDocsプラグイン mkdocs-macros-plugin のinstall
    更新履歴表示(macros)

    pip install mkdocs-macros-plugin

  • install が完了したか確認します。

    pip list

    私の pip list
    C:\Users\●●●>pip list
    Package                                   Version
    ----------------------------------------- ----------
    appdirs                                   1.4.4
    astroid                                   2.15.8
    Babel                                     2.12.1
    bracex                                    2.3.post1
    certifi                                   2023.7.22
    charset-normalizer                        3.2.0
    click                                     8.1.7
    colorama                                  0.4.6
    dill                                      0.3.7
    docutils                                  0.20.1
    fissix                                    21.11.13
    fontawesome-markdown                      0.2.6
    future                                    0.18.3
    ghp-import                                2.1.0
    gitdb                                     4.0.10
    GitPython                                 3.1.34
    idna                                      3.4
    importlib-metadata                        6.7.0
    isort                                     5.11.5
    Jinja2                                    3.1.2
    lazy-object-proxy                         1.9.0
    Markdown                                  3.4.4
    MarkupSafe                                2.1.3
    mccabe                                    0.7.0
    mergedeep                                 1.3.4
    mkdocs                                    1.5.2
    mkdocs-awesome-pages-plugin               2.9.2
    mkdocs-git-revision-date-localized-plugin 1.2.0
    mkdocs-macros-plugin                      0.7.0
    mkdocs-material                           9.2.7
    mkdocs-material-extensions                1.1.1
    modernize                                 0.8.0
    natsort                                   8.4.0
    packaging                                 23.1
    paginate                                  0.5.6
    pathspec                                  0.11.2
    pip                                       24.0
    pip-review                                1.3.0
    platformdirs                              4.0.0
    pyenchant                                 3.2.2
    Pygments                                  2.16.1
    pylint                                    2.17.7
    pymdown-extensions                        10.2.1
    pymel                                     1.4.0
    PySide2                                   5.15.2.1
    python-dateutil                           2.8.2
    pytz                                      2023.3
    PyYAML                                    6.0.1
    pyyaml_env_tag                            0.1
    regex                                     2022.10.31
    requests                                  2.31.0
    setuptools                                41.2.0
    shiboken2                                 5.15.2.1
    six                                       1.16.0
    smmap                                     5.0.0
    termcolor                                 2.3.0
    tomli                                     2.0.1
    tomlkit                                   0.12.3
    typed-ast                                 1.5.5
    typing_extensions                         4.7.1
    urllib3                                   2.0.4
    watchdog                                  3.0.0
    wcmatch                                   8.4.1
    wheel                                     0.42.0
    wrapt                                     1.16.0
    zipp                                      3.15.0
    

インストールが完了したので、一つづつ、運用に入ってゆきます。

-余談-

当方は今まで、Maya と python との連携にしか、着手してきた経験がありませんでした。
python運用には、IDE で、PyCharm Pro を活用しています。
しかし、Mayaと無関係な python運用 を、しっかり行ってきた経験が無く、
これから述べることは、その運用方法も補っています。

Pythonモジュール GitPythonの運用 までの流れ

Pythonモジュール GitPython を利用した main.py ファイルの配置場所の特定

先ず、当方がこれまでMkdocsを独自運用していた場所である、以下
C:\Users\●●●\work\mkdocs\tech_memo
が配置場所に該当します。

-余談-

当方は今まで、Mkdocsの構築には、windows コマンドプロンプト で行ってきました。
故に、、しっかりとした、python運用 は始めてです。つまり、IDE PyCharm Pro との連携も初めてです。

そして、
このプロジェクト直下に、以下のようなmain.pyを作成していくそうです。
参考基となったサイト3 flap1さん

main.py
def define_env(env):
    # マクロ関数をここに定義 

後に、
MkDocsのプロジェクトの管理用の Pythonモジュール GitPython を利用した、main.py ファイルを配置する予定です。
そして、
この、main.py を活用すれば、pythonの実行結果を、mkdocs記事の指定箇所に、任意の記事が埋め込めるようになるそうです。
main.py ファイルについては、後述します。

◆PyCharm 新規プロジェクト の作成

Mayaとは無関係な、PyCharm 新規プロジェクト を作成します。

クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

Info

Mkdocsプロジェクト専用として、既存な当該フォルダで、これまでずっとコマンドプロンプトでの独自運用を行っていました。
ですので、厳密には、新規プロジェクトでは無いですよね!
故に、上記の注意喚起が現れます。
そのまま、続行してください。

また、.gitファイルの存在も見落とせませんね!

すると、これまでの運用フォルダ階層下に、以下、.idea, .venv フォルダが新たに作成されます。

クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

Info

これまでずっと独自運用しているMkdocsプロジェクトは、予め、Githubとの連携は実現済みであるというこは、改めて述べておきます。

クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

◆PyCharm 新規プロジェクト 作成後の諸々の設定

次に、最終的に望みとなる main.py を作成し、実行するためには、
先に install 済みの、GitPythonモジュール が、main.py にちゃんと from git import Repo 出来ないと、運用はできません。

クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

そこで、GitPythonモジュール の環境の構築が必要となります。
それが、設定 > プロジェクト > Pythonインタープリター設定 です。
クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

つまり、これを venv設定と言います。
予め、pip install された、モジュールを、任意のプロジェクト配下において、個別に環境設定できる設定なのです。
クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

新規プロジェクト時は、クリーンな環境のままですので、添付画像のように、単純な構成から始まります。

緑色の+ボタン
を押下し、GitPythonモジュール の個別インストールです。
クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

以下の順です。

クリックで拡大
PyCharm_新規プロジェクト
画像1

  1. 検索フィールドに、GitPython と入力し、
    予め pip installされている、幾多のモジュールの内から、GitPythonを特定し、
    MkDocsのプロジェクト"C:\Users\●●●\work\mkdocs\tech_memo" へ、インストールします。画像1
  2. パッケージのインストール ボタンの押下です。画像1
  3. 表示の左下が、変化します。画像2
  4. すると前回と違って、パッケージ内容が、インストールした分、増加しているのが見て取れます。画像3

クリックで拡大
PyCharm_新規プロジェクト
画像2

PyCharm_新規プロジェクト
画像3

試しに、
何でも良いので、pythonファイルを作成し、from git import Repo してみると、
これまで上手くいっていなかった import が出来るようになっているのがわかります!

クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

以上、GitPythonモジュール の環境構築についてでした。

MkDocsプラグイン mkdocs-macros-pluginの運用 までの流れ

Info

これはMkDocsのビルドプロセスに干渉して、マクロ機能を提供するためのものです。
マクロプラグインは、MkDocsのプロジェクトにカスタム機能を追加し、ビルド時に特定の処理を行うための手段を提供します。

具体的には、
Mkdocsの各々の記事をコントロールしている、任意の.md ファイル 内において、

{update_info(5,'######')}}

等と記述挿入することで、例えば、以下のような過去の履歴表示が、最終的にHTMLページ上で実現できるようになります。

Info

<2024-04-01 16:59:06> 概要(Summary): mkdocs macro document, update.¶
<2024-04-01 16:54:53> 概要(Summary): mkdocs macro document, update.¶
<2024-04-01 16:52:08> 概要(Summary): mkdocs macro document, upload.¶
<2024-04-01 16:50:33> 概要(Summary): mkdocs macro document, upload.¶
<2024-04-01 16:49:47> 概要(Summary): mkdocs macro document, upload.¶

◆プラグイン を yamlファイル へ記述 設定

MkDocs用のプラグインを通すためには、設定用に、MkDocsのプロジェクトをコントロールする為の yamlファイル が存在します。
それが、MkDocsのプロジェクト C:\Users\●●●\work\mkdocs\tech_memo 階層直下にある、mkdocs.yml ファイルです。
そのファイルの、pluginsの箇所に、macros と追記します。

plugins:
  - macros

私の mkdocs.yml
...
# 右上にGitリポジトリのリンクを追加できます。自動でスター数とフォーク数が表示されます。
repo_url: https://github.com/44hero/tech_memo
repo_name: 44hero/tech_memo
...
theme:
  name: 'material'
  version: 9.2.7
  language: 'ja'
  favicon: images/favicon.png
  ...
...
plugins:
  ...
  - git-revision-date-localized:  # 改訂日挿入プラグイン 導入
      ...
  ...
  - awesome-pages  # 柔軟な page 作成をアシストするプラグイン 導入
  - macros  # mkdocs macro 2024-3-29 新規導入
  ...
...

◆PyCharm 新規プロジェクト への諸々の設定

前述のGitPythonモジュールと同様に、
この度のmkdocs-macros-pluginプラグインも、設定 > プロジェクト > Pythonインタープリター設定 を行います。

緑色の+ボタン
を押下し、mkdocs-macros-pluginプラグイン の個別インストールです。
クリックで拡大
PyCharm_新規プロジェクト
PyCharm_新規プロジェクト

以下の順です。

クリックで拡大
PyCharm_新規プロジェクト
画像4

  1. 検索フィールドに、mkdocs-macro と入力し、
    予め pip installされている、幾多のプラグインの内から、mkdocs-macro-pluginを特定し、
    MkDocsのプロジェクト"C:\Users\●●●\work\mkdocs\tech_memo" へ、引き続きインストールします。画像4
  2. パッケージのインストール ボタンの押下です。画像4
  3. 表示の左下が、変化します。画像5
  4. すると前回と違って、パッケージ内容が、インストールした分、また新たに増加しているのが見て取れます。画像6
    他にも、必要なものが、自動で入っているようですね。

クリックで拡大
PyCharm_新規プロジェクト
画像5

PyCharm_新規プロジェクト
画像6

以上、mkdocs-macro-pluginプラグイン の環境構築についてでした。

main.pyの配置

MkDocsのプロジェクトの管理用の Pythonモジュール GitPython を利用した、main.py ファイルを配置します。
main.py を活用し、pythonの実行結果を、mkdocs記事の指定箇所に、任意の記事が埋め込めるようになります。
MkDocsのプロジェクト"C:\Users\●●●\work\mkdocs\tech_memo"直下に、
一例として、
以下のような main.py を作成配置します。アレンジを加えています。

参考基となったサイト1 Andoさん(reincarnation_tech)

私の main.py
main.py
# -*- coding: utf-8 -*-

import os
import os.path
import re
import codecs
from datetime import datetime
from pprint import pprint
from git import Repo


def define_env(env):
u""" < ***関数 です >

    update_info()関数が呼ばれ、その結果が出力されます。
        具体的には、Gitリポジトリから最新のコミット情報を取得し、それを整形して出力します。
    しかし、このコードをそのまま実行すると、update_info()関数を利用するための環境が提供され
        ていないため、エラーが発生します。
            このスクリプトが動作するには、define_env()関数が外部で呼ばれ、
                適切な環境が提供される必要があります。
    つまり、このスクリプトは、どこかの環境で使用されることを想定しています。
        define_env()関数が提供される環境の中で、update_info()関数を呼び出すことで、
            Gitリポジトリからの情報を取得し、整形された結果が得られます。
    """
    space = ' '

    def getTitle(md):
        if os.path.exists(md):
            with codecs.open(md, 'r', 'utf8') as f:
                for i in f.readlines():
                    if re.search("^title:", i):
                        return i.strip().split(":")[1]
        return None

    def createNewTitle(title):
        titleSepList = title.split('/')
        titleSepList.remove(titleSepList[-1])
        # print(titleSepList)
        # 新しいリストを初期化
        new_titleSepList = []
        # 各要素に対して処理を行う
        for file_name in titleSepList:
            # 先頭から012番目までが数字と_で構成されているかをチェック
            if re.match(r'^[\d_]{1,3}', file_name):
                # 数字と_を除去して新しいリストに追加
                new_titleSepList.append(file_name[3:])
            else:
                # 数字と_が含まれていない場合はそのまま新しいリストに追加
                new_titleSepList.append(file_name)
        # print('###' * 11 + '11')
        # print(new_titleSepList)
        # 'tech_memo' を0番目に追加する
        new_titleSepList.insert(0, 'tech_memo')
        # '/' でリストを結合して一つの文字列にする
        new_title: str = '/'.join(new_titleSepList)
        # print(new_title)
        return new_title

    @env.macro
    def update_info(num, header = "##", addRootPathOption = ''):
        u"""

        :param int num: 引数1番目: 表示件数を指定します
        :param string header: 引数2番目: markdown記述の、見出しの大きさの指定の数値です
        :param string addRootPathOption: 引数3番目: 基本的には、''(空表記)で充分ですが、
                                        '../'(ルートまで遡る)を必要とする時のオプションです
        :return: "".join(msg)  # start: "\n".join(msg)
        :rtype: str
        """
        global new_title
        repo = Repo(os.getcwd())
        msg = []
        # print('###' * 30 + '30')
        # print(addRootPathOption)
        for commit in repo.iter_commits('gh-pages', max_count = num):  # default: 'master'
            dt = datetime.fromtimestamp(commit.committed_date)
            buff = commit.message.split("\n")
            # print('###' * 30)
            # print(buff, dt)
            msg.append(f"\n------\n"
                       f"{header}{space}"  # note): <br> is 強制改行
                       f"{dt.strftime('<%Y-%m-%d %H:%M:%S>')}{space}"
                       f"概要(Summary):{space}"
                       f"{buff[0]}<br>"
                       )
            # msg.append("")
            # msg.append(f'------<br>')
            # print('###' * 30)
            # print(msg)
            if len(buff) > 2:
                # 更新コメントがちゃんと書いてあったら詳細を書く
                msg += buff[2:]
            # print('###' * 30)
            # print(msg)
            # 更新ページ
            files = commit.stats.files.keys()
            # print('###' * 30)
            # print(files)
            for f in files:
                # print('###' * 27 + '27')
                # print(f)
                ext = os.path.splitext(f)[1]
                # print('###' * 25 + '25')
                # print(ext)
                if ext == ".html":  # default: '.md'
                    link = re.sub("^docs/", "", f.replace("\\", "/"))  # default: '^docs/'
                    # print('###' * 20 + '20')
                    # print(link)
                    # print(os.getcwd() + "/" + f)
                    title = getTitle(os.getcwd() + "/" + f)
                    # print('###' * 15 + '15')
                    # print(title)
                    if not title:
                        title = link
                        # print('###' * 10 + '10')
                        # print(link)
                        # print(title)
                        new_title = createNewTitle(title)
                        # print('###' * 8 + '8')
                        # print(new_title)
                        if not addRootPathOption == '../':
                            print(f"[{new_title}]({link})<br>")
                            msg.append(f"[{new_title}]({link})<br>")  # start: f"[* {new_title}]({link})"
                        elif addRootPathOption == '../':
                            print(f"[{new_title}]({addRootPathOption + link})<br>")
                            msg.append(f"[{new_title}]({addRootPathOption + link})<br>")  # start: f"[* {new_title}]({link})"
                    # msg.append(f"[{title}]({link})")
                elif ext == '.gz':
                    pass
        # print('###' * 2 + '2')
        # pprint(msg)
        # '* [tech_memo](404.html)' があれば除外する
        if '[tech_memo](404.html)<br>' in msg:
            msg.remove('[tech_memo](404.html)<br>')
        return "".join(msg)  # start: "\n".join(msg)

以上の手順を踏みます。

●Mkdocsのビルド

さて、改めて、Mkdocsを、これまでのようにビルドしてみます。

以下参考まで 私のビルド参考ページです。
mkdocs gh-deploy¶ビルド参考ページ

クリックで拡大
PyCharm_新規プロジェクト
MkdocsをビルドしたHTML画面

完成です。
上手く、履歴が任意の箇所に表示されます。




以上



最終更新日: 2024年4月18日 09:56:48