use docval

[ReiHashimoto]

docvalを使用して関数のドキュメントを生成するように試験的に改修
あくまで試験的な実装のため、caiman_mc, caiman_cnmfのみ対応し、他の関数は無効にしている

本実装方針で問題ない場合、以下の残タスクを対応予定

• 他のwrapper関数への適用
• 不要なファイル群の削除
• テストコードの改修
• 関数追加方法などのドキュメンテーションの修正
• wrapper関数のドキュメンテーションへの導線追加
• 追加されたdoc属性を使用し、GUIでのパラメータ説明表示機能の実装（別PRで対応）

wrapper関数の実装方法

# _以下のmoduleをimport
from hdmf.utils import docval, popargs
from studio.app.common.core.param.param import Param
from studio.app.common.core.wrapper.algo import AlgoTemplate

# AlgoTemplateクラスを継承してwrapper関数のクラスを定義する
class SomeFunction(AlgoTemplate):
    # importしたParamクラスを使用して各種引数を定義する
    # ノードで入出力のコネクタとなるデータクラスを定義
    _INPUT_NODES = [
        Param(name="images", type=ImageData),
        # 接続しなくても良いOptionalなコネクタの場合は、default=Noneとする
        Param(name="iscell", type=IscellData, default=None)
    ]
    _OUTPUT_NODES = [Param(name="fluorescence", type=FluoData)]
    _DEFAULT_PARAMS = [
        Param(
            name="param1",
            type=str,  # typeはpythonの型をそのまま使用する
            default="param1_value",
            doc="param1_doc",
        ),
        # GUIで階層で表示させるパラメータの場合は、sectionを使用する。
        Param(
            name="param2",
            type=int,
            default=2,
            section="section_A",
            doc="param2_doc",
        ),
        # sectionは/を区切り文字として、ネストさせることができる。
        Param(
            name="param3",
            type=list,
            default=[3, 3],
            section="section_A/section_AA",
            doc="param3_doc",
        )
    ]
    
    # Snakemakeで実行する関数は名称をfuncとする
    # 関数にdocvalデコレータを使用し、各パラメータを展開して渡す
    # sectionなど、本来docvalに存在しない属性を使用しているため、コンバート用の関数を使用する
    # docvalによってパラメータが渡されるため、funcの引数はself, **kwargsとする
    @docval(
        *AlgoTemplate.docval_params([*_INPUT_NODES, *_DEFAULT_PARAMS]),
        **AlgoTemplate.docval_returns([*_OUTPUT_NODES]),
    )
    def func(self, **kwargs):
        """some_function
        
        ここに関数の概要を記載する
        """
        # output_dir, function_idはWrapperクラスで抱えているため、selfから取得できる
        print(self.output_dir)
        print(self.function_id)
        
        # nwbパラメータも同様にselfから取得できる
        # 元々引数として明示はなかったが、一部関数ではimaging_rateを取得するためにkwargsから取り出していた
        fr = self.nwb_params.get("imaging_plane", {}).get("imaging_rate", 30)
        
        # 処理を別メソッドに切り出す場合、クラスメソッドとして定義して呼び出す(後述)
        related_results = self.related_function(x, y)
        
        # その他は変更点なし
        ...
        return info
    
    # funcから呼び出す関数を定義する場合はクラスメソッドとして定義する
    @classmethod
    def related_function(cls, param_x, param_y):
        ...
        return z

wrapper_dictは以下のように変更

# importするのが関数ではなくクラスになる
from studio.app.optinist.wrappers.some.some import SomeFunction

some_wrapper_dict = {
    "some": {
        "some_function": {
            # wrapper関数のクラスの**インスタンス**を渡す
            # ()が必要な点に注意
            "function": SomeFunction(),
            "conda_name": "some",
        }
    }
}

documentの確認方法

以下のコマンドでshpinxをローカル起動

# installしていない場合のみ
pip install -e '.[doc]'

make docs

起動後に、以下のパスからcaimanのdocumentが参照可能
http://localhost:8001/modules/studio.app.optinist.wrappers.caiman.html
これらのdocumentへの導線追加は未対応

その他

• 本改修に伴い、workflow.yamlおよびexperiment.yamlについて、パラメータ部分(snakemake, nwb, nodeパラメータ)のフォーマットが変わる(dataType, docなどの属性が追加されている)が、下位互換性を持たせているためversion1以降のexperimentは読み込み可能

[itutu-tienday]

細かな指摘もありますが、
一旦いくつかフィードバックを行います。

[itutu-tienday]

@ReiHashimoto

以下のコマンドでshpinxをローカル起動

# installしていない場合のみ
pip install -e '.[doc]'
make docs

上記を試してみたところ、こちらの環境で以下のようなエラーが出ていますが、動作はしますでしょうか？

$ cd {BAREBONE_INSTALL_DIR}
$ make docs

rm -rf docs/_build/
# pip install -e '.[doc]'
sphinx-apidoc -f --no-toc -o ./docs/modules ./studio
make: sphinx-apidoc: No such file or directory
make: *** [Makefile:35: docs] Error 127

[ReiHashimoto]

@itutu-tienday

上記を試してみたところ、こちらの環境で以下のようなエラーが出ていますが、動作はしますでしょうか？

shpinxのversionの問題で、styleが読み込めていなかったようです。
（リリース時に問題はなかったのですが...）
versionを下げて対応しましたので、再度お試しください。

[itutu-tienday]

@ReiHashimoto

shpinxのversionの問題で、styleが読み込めていなかったようです。

make docs のエラーの件ですが、現在の最新版でも、同じエラーが発生している模様です。
→こちらの環境では、sphinx-apidoc のコマンドが見つからない様なのですが、そのあたりが要因でしょうか？（pip install -e '.[doc]' は実施済）

[ReiHashimoto]

@itutu-tienday

make docs のエラーの件ですが、現在の最新版でも、同じエラーが発生している模様です。 →こちらの環境では、sphinx-apidoc のコマンドが見つからない様なのですが、そのあたりが要因でしょうか？（pip install -e '.[doc]' は実施済）

poetry導入のPRをマージ済なので、poetry install --with doc --no-rootを試していただけますか？
その後にpoetry show --only docでsphinxcontrib-apidocがインストール済(パッケージ名が青色)であればsphinx-apidocコマンドは通るかと思います。

[ReiHashimoto]

他のアルゴリズムへの適用中に以下の課題が発覚
対応方針検討中

• 異なるセクションでパラメータ名が重複するケースがある
  • docvalでは変数をフラットに受け取るため、セクションが別れていても変数名が重複すると受け入れ不可
  • 対象
    • lccd_cell_detection
      • min_area, max_area, sparseがblob_detector, roi_integrationのセクションで重複
    • svm
      • C, kernel, degree, gamma, coef0, shirinking, tol, decision_function_shapeがgrid_search.param_grid, SVCのセクションで重複
    • granger
      • maxlag, autolagがadfuller, cointのセクションで重複

[itutu-tienday]

poetry導入のPRをマージ済なので、

poetry の環境で、make docs が実行できることを確認しました。
※なお pip install 環境でも、sphinxcontrib-apidoc は導入されていましたが、コマンドにパスが通されていなかったようです（？）

ただし、その後以下のようなエラーが出ています。 （結果的にHTMLが生成されていない模様）
※現状は優先ではありませんので、また都合の良いタイミングでご確認いただければと思います。

$ make docs
〜〜 中略 〜〜
Theme error:
An error happened in rendering the page gui/index.
Reason: UndefinedError("'style' is undefined")

[ReiHashimoto]

@itutu-tienday

poetry の環境で、make docs が実行できることを確認しました。 ※なお pip install 環境でも、sphinxcontrib-apidoc は導入されていましたが、コマンドにパスが通されていなかったようです（？）

ただし、その後以下のようなエラーが出ています。 （結果的にHTMLが生成されていない模様） ※現状は優先ではありませんので、また都合の良いタイミングでご確認いただければと思います。

$ make docs
〜〜 中略 〜〜
Theme error:
An error happened in rendering the page gui/index.
Reason: UndefinedError("'style' is undefined")

ご確認ありがとうございます。こちらが以下のコメントで話題にしていた内容なのですが、再度調査したところ、問題はsphinx-rtd-themeのバージョンが古いことでした。

shpinxのversionの問題で、styleが読み込めていなかったようです。
（リリース時に問題はなかったのですが...）
versionを下げて対応しましたので、再度お試しください。

こちらについては、#152 で対応しているので、こちらのPR mergeで解消はします。
取り急ぎそれまでの確認にあたっては

poetry update --only doc sphinx-rtd-theme

でバージョンを更新できるはずです。

[itutu-tienday]

poetry update --only doc sphinx-rtd-theme

上記で、HTMLのbuild に成功したようです。フォローありがとうございます。

[ReiHashimoto]

#232 での実装となるため、こちらはclose