プラグイン作成の流れ

🔌

NKSSG では、プラグインを作り、機能を拡張することができます。ここでは、プラグインを作る流れを説明していきます。

プラグイン作成の流れ

NKSSG にはプラグイン機能があり、好きな機能を追加することができます。Python でできることなら（ファイル削除なども含めて）だいたい何でもできます。

便利な反面、少し危険でもあります。そのため、テーマよりもはじめの一歩を少しめんどくさくしています（といってもそんなめちゃくちゃ難しいわけではないですが）。

一言でいうと、パッケージ化してインストールできるようにする作業が必要になります。

以下では、順番に作成手順を見ていきます。

作業場所の作成

まず、プラグイン作成の作業を行う場所を決めましょう。NKSSG のサイトを作っているところと同じ場所で構いません。仮想環境がそのまま使えるので、むしろ好都合です。ここに、例えば、pluginsという名前のフォルダを作ります。

root
├── docs
│   ├── page
│   └── post
├── plugins   <= 新規作成
├── public
├── static
├── themes
└── nkssg.yml

空のプラグイン作成

次に、プラグインのひな型を作ります。最低限、以下の内容を書いておけばいいです。何もしないプラグインです。

from nkssg.structure.plugins import BasePlugin

class SamplePlugin(BasePlugin):
    def __init__(self):
        pass

sample.py という名前にして、plugins フォルダの下に保存しましょう。

setupの作成

次に、setup.pyを作って、インストールできるようにしましょう。自分で使うだけであれば、最低限以下の内容があればいいです。

from setuptools import setup

setup(
    name="nkssg-plugin",
    entry_points={
       'nkssg.plugins': [
            'sample = sample:SamplePlugin',
       ]
    },
)

name のところは、pip で使う名前です。後でインストールをするときに使います。

nkssg.plugins の後にプラグインの設定を書くと、NKSSG はプラグインとして認識し、読みこむようになります。

sample = sample:SamplePlugin のうち、イコールの左側は、nkssg.yml の plugins で設定するときに使う名前です。プラグインを作ってインストールしても、nkssg.yml で設定しないと有効化されません。イコールの右の部分は、ファイル名とクラス名です。

プラグインのインストール

これで、プラグインをインストールできるようになりました。やってみましょう。次のコマンドを実行してみます。

pip install -e plugins

これで、自作プラグインのインストールができます。最後の plugins は setup.py のあるフォルダを指定します。これにより、setup.pyの内容をpipが解釈して、sampleプラグインが使えるようになります。

-eというオプションは、「編集可能モード」のことです。通常、インストールしたコードを修正した場合、再インストールが必要です。しかし、毎回インストールをするのは面倒です。-eをつけてインストールすれば、コードを編集するたびにその内容が反映されます。

編集可能モードでインストールしているかどうかは、pip listで確認できます。一覧の中に、今インストールしたプラグインがあるはずで、その横にPC内のパスが入っていれば、「編集可能モードでインストールした」ことを表しています。

プラグインの有効化

自作プラグインのインストールができたので、これを NKSSG で使えるように設定しましょう。nkssg.yml で、次のようにします。

plugins:
  (他のプラグインは省略)
  - sample

これでOKです。もし、値を設定して渡したい場合には次のようにします。

plugins:
  - sample:
      xxx: 'yyy'

これらは、デフォルトで有効になっているプラグインの設定が参考になるでしょう。

初プラグイン作成

ここまでで、自作プラグインが使えるようになりました。が、本当に使えるのかどうか、まだよくわからないですね。簡単なコードを書いて、確かめてみましょう。

NKSSG では、サイトを作成する処理のいたるところに、処理を挿入できるようになっています。「このタイミングで、この処理をする」というのを書いていくことになります。

ここでは、サイトの作成にどれくらい時間がかかったか、出力するプラグインを作ってみましょう。次のように sample.py を書き直してみます。

import time

from nkssg.structure.plugins import BasePlugin

class SamplePlugin(BasePlugin):
    def __init__(self):
        self.start = time.time()
        self.print_flag = True

    def on_end(self, *args, **kwargs):
        if self.print_flag:
            diff = time.time() - self.start
            print('Diff: {:.2f}'.format(diff) + ' [sec]')
            self.print_flag = False

まず、今の時刻を保持しておきます。そして、on_end という、すべての処理が終わったときに呼び出されるタイミングで、メモしておいた時間との差を出力しています。nkssg serve を実行している場合は、保存するたびに on_end が呼び出されるので、はじめの1回だけ実行されるように flag を設定しています。

編集可能モードでインストールしているので、ファイルを上書きするだけで、今作ったプラグインの内容が反映されます。nkssg serve や nkssg build を実行すると、作成にかかった時間がターミナル上に表示されることがわかります。

次は何をする？

ここまでで、プラグインを作るための流れを見てきました。

最後の「初プラグイン作成」でも見たとおり、プラグインでは「どのタイミングで、何を実行するか」を書いていきます。そのため、プラグインを作るには、以下のことを知っておく必要があります。

• NKSSG の処理の流れ
  • どの時点で何が計算できているか
• NKSSG のイベント
  • 処理を挿入できるタイミング
• NKSSG の処理で使えるもの
  • 計算済みのデータの呼び出し方など

処理の流れは、次の記事にまとめています。TODO

イベントは、次の記事にまとめています。何を受け取って、何を返すかをまとめています。TODO

処理で使えるものは、次の記事にまとめています。TODO

少し大変ですが、これらを踏まえて、自分の好きなようにカスタマイズしていきましょう。