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
-
バージョンの一番高いpythonバージョンの出力
python -V
orpython --version
-
pip自身のインストールされている場所を示す
pip show pip
私の pip show pip
-
実際のパス "c:\users\●●●\program\python377\lib\site-packages" を確認
-
拡張機能 mkdocs-material のバージョンを調べる e.g.): mkdocs-material
pip show mkdocs-material
私の pip show mkdocs-material
どうやら、当該の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
インストールが完了したので、一つづつ、運用に入ってゆきます。
-余談-
当方は今まで、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さん
後に、
MkDocsのプロジェクトの管理用の Pythonモジュール
GitPython
を利用した、main.py ファイルを配置する予定です。そして、
この、main.py を活用すれば、pythonの実行結果を、mkdocs記事の指定箇所に、任意の記事が埋め込めるようになるそうです。
main.py ファイルについては、後述します。
◆PyCharm 新規プロジェクト の作成¶
Mayaとは無関係な、PyCharm 新規プロジェクト を作成します。
Info
Mkdocsプロジェクト専用として、既存な当該フォルダで、これまでずっとコマンドプロンプトでの独自運用を行っていました。
ですので、厳密には、新規プロジェクトでは無いですよね!
故に、上記の注意喚起が現れます。
そのまま、続行してください。
また、.git
ファイルの存在も見落とせませんね!
すると、これまでの運用フォルダ階層下に、以下、.idea
, .venv
フォルダが新たに作成されます。
Info
これまでずっと独自運用しているMkdocsプロジェクトは、予め、Githubとの連携は実現済みであるというこは、改めて述べておきます。
◆PyCharm 新規プロジェクト 作成後の諸々の設定¶
次に、最終的に望みとなる main.py を作成し、実行するためには、
先に install 済みの、GitPython
モジュール が、main.py にちゃんと from git import Repo
出来ないと、運用はできません。
そこで、GitPython
モジュール の環境の構築が必要となります。
それが、設定 > プロジェクト > Pythonインタープリター設定
です。
クリックで拡大
PyCharm_新規プロジェクト
つまり、これを venv設定と言います。
予め、pip install
された、モジュールを、任意のプロジェクト配下において、個別に環境設定できる設定なのです。
クリックで拡大
PyCharm_新規プロジェクト
新規プロジェクト時は、クリーンな環境のままですので、添付画像のように、単純な構成から始まります。
緑色の+ボタン
を押下し、GitPython
モジュール の個別インストールです。
クリックで拡大
PyCharm_新規プロジェクト
以下の順です。
- 検索フィールドに、
GitPython
と入力し、
予めpip install
されている、幾多のモジュールの内から、GitPython
を特定し、
MkDocsのプロジェクト"C:\Users\●●●\work\mkdocs\tech_memo" へ、インストールします。画像1 - パッケージのインストール ボタンの押下です。画像1
- 表示の左下が、変化します。画像2
- すると前回と違って、パッケージ内容が、インストールした分、増加しているのが見て取れます。画像3
試しに、
何でも良いので、pythonファイルを作成し、from git import Repo
してみると、
これまで上手くいっていなかった import が出来るようになっているのがわかります!
以上、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
と追記します。
私の mkdocs.yml
◆PyCharm 新規プロジェクト への諸々の設定¶
前述のGitPython
モジュールと同様に、
この度のmkdocs-macros-plugin
プラグインも、設定 > プロジェクト > Pythonインタープリター設定
を行います。
緑色の+ボタン
を押下し、mkdocs-macros-plugin
プラグイン の個別インストールです。
クリックで拡大
PyCharm_新規プロジェクト
以下の順です。
- 検索フィールドに、
mkdocs-macro
と入力し、
予めpip install
されている、幾多のプラグインの内から、mkdocs-macro-plugin
を特定し、
MkDocsのプロジェクト"C:\Users\●●●\work\mkdocs\tech_memo" へ、引き続きインストールします。画像4 - パッケージのインストール ボタンの押下です。画像4
- 表示の左下が、変化します。画像5
- すると前回と違って、パッケージ内容が、インストールした分、また新たに増加しているのが見て取れます。画像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 | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 |
|
以上の手順を踏みます。
●Mkdocsのビルド¶
さて、改めて、Mkdocsを、これまでのようにビルドしてみます。
以下参考まで 私のビルド参考ページです。
mkdocs gh-deploy¶ビルド参考ページ
完成です。
上手く、履歴が任意の箇所に表示されます。
¶
以上