関数parameterの説明を表示

oist / optinist

calcium imaging pipeline tool

GNU General Public License v3.0

37 stars 13 forks source link

方針案

Frontend

サイドバーでパラメータ名をクリックした際にpopoverでdescriptionを表示させる

主な改修対象

frontend/src/components/common/ParamFormItemCreator.tsx

ParamChildItemがRightDrawerのパラメータキー部分のため、こちらにpopoverを追加

frontend/src/utils/param/ParamType.ts

frontend/src/api/params/Params.ts

frontend/src/utils/param/ParamUtils.ts(convertToParamMap)

BackendのAPI仕様に対応するようにResponse型などの修正

Backend

/params/{name}APIでkey, value以外にdescriptionを返す

parameterのyamlの構造を

key1: value1
key2:
  key2-1: value2-1
  key2-2: value2-2

形式から、以下のような形式に変更

key1:
  param_description: ...
  value: value1
key2:
  children:
    key2-1:
      value: value2-1
      param_description: ...
    key2-2:
      value: value2-2
      param_description: ...

nwb.yamlでdescriptionのキー名が使用されているため、param_descriptionなどの重複しにくいkey名にする必要がある

主な改修対象

optinist/config配下のyamlの構造変更およびパラメータ説明文の記載

以下はv0.4.0時点での数で、v0.5.0の実装の際に追加の可能性あり
ファイル数: 22
パラメータ数: 340
ネストしている場合末端のkey, valueのセットのみカウント

ParamType, ParamReaderを追加で作成

現状はファイルの読み込みに汎用的なConfigReaderを使用しているが、パラメータとしてのkey, valueとアプリ定義のkey, valueを識別するため型に落とし込む

optinist/api/workflow/workflow_params.py

ConfigReader --> ParamReaderに置き換え
get_typecheck_paramsからreturnするparamsは従来のkey, valueのみになるようにする

optinist/routers/params.py

ConfigReader --> ParamReaderに置き換え

アルゴリズムについても説明を追加する場合

方針案

Frontend

既存のnode edgeのホバー表示にデータ型の説明を追加で表示
関数名クリック時にpopoverで関数の説明を表示（ドラッグ操作とは共存可）

主な改修対象

frontend/src/api/algolist/AlgoList.ts
- AlgoListDTO, AlgorithmInfoクラスにdescription追加
frontend/src/components/FlowChart/FlowChartNode/AlgorithmNode.tsx
- ArgHandle, ReturnHandleにdescription追加
frontend/src/components/FlowChart/TreeView.tsx
- AddButtonにpopover

Backend

/algolistAPIのresponseに関数およびパラメータのdescriptionを追加
メンテナンス性を考慮しdocstringに記述したものを利用する

主な改修対象

optinist/routers/model.py
- Algoクラスにdescription追加
- 関数自体の説明
- Arg, Returnクラスにdescription追加
- 引数、返り値のデータクラスの説明
wrappers配下の関数(wrapper_dictとして出力されるもの、29)
- docstringとして関数の説明を追加
optinist/api/dataclass配下のデータクラス
- docstringとしてクラスの説明を追加
optinist/routers/algolist.py
- get_nest_dict
- wrapper関数のdocstringをinspect.getdocで取得してAlgoに追加
- _args_list
- データクラスのdocstringをx.annotation.__doc__で取得してArgに追加
- _return_list
- データクラスのdocstringをv.__doc__で取得してReturnに追加

懸念事項

Input, Outputのデータクラスの説明について
- 関数のコンテキストで内容を分けることは上記仕様ではできない
- 説明量によってはパイプライン構築の操作時に邪魔になる

oist / optinist