Add docs page

.gitignore

@@ -20,7 +20,7 @@ __pycache__/
 
 # Distribution / packaging
 .Python
-build/
+# build/
 develop-eggs/
 dist/
 downloads/

docs/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = _build
+BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: c250397ad3308c0da146643e8d1c8417
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/command_usage.rst.txt

@@ -0,0 +1,106 @@
+コマンドの使い方
+######################################################
+
+convert
+******************************************************
+
+dbtモデルファイルを生成します
+
+.. code-block:: shell
+
+  $ prep2dbt convert -f /path/to/file.tfl
+
+オプション
+======================================================
+
+.. option:: -f, --flow-file 
+
+  変換するフローファイル（.tfl/.tflx）のパス。
+
+.. option:: -w, --work-dir   
+
+  作業ディレクトリパス。デフォルトはカレントディレクトリです。
+
+.. option:: -d, --dialect 
+
+  SQLのダイアレクト。サポートしているDBは、 ``'postgres'`` , ``'duckdb'`` , ``'snowflake'`` です。
+
+.. option:: -s, --source-name 
+
+  source生成時のnameです。デフォルトは'SOURCE'です。
+
+.. option:: -t, --tags 
+
+  生成するモデルに付与されるタグです。カンマ区切りで複数件指定できます。
+
+.. option:: -p, --prefix 
+
+  生成するモデルの、名前の先頭に追加できる文字です。
+
+出力
+======================================================
+
+.. code-block:: shell
+
+  $ prep2dbt convert -f flow.tfl
+  ========================================================= 処理したステップ ========================================================
+  RAW_PAYMENTS (RAW_PAYMENTS)                                                                                             [正常終了]
+  stg_payment                                                                                                             [正常終了]
+  stg_customer                                                                                                            [正常終了]
+  final_join_1                                                                                                            [正常終了]
+  orders                                                                                                                  [正常終了]
+  orders_rename_cols                                                                                                      [正常終了]
+  customer_orders_most_recent_order                                                                                       [正常終了]
+  customer_orders                                                                                                         [正常終了]
+  customer_payments_join                                                                                                  [正常終了]
+  customer_payments_aggregate                                                                                             [正常終了]
+  customers                                                                                                               [正常終了]
+  write customers                                                                                                    [不明なステップ]
+  unstack payment methods                                                                                     [カラムが特定できません]
+  order_payments                                                                                                          [正常終了]
+  order_payment_cleansed                                                                                                  [正常終了]
+  customer_payments                                                                                                       [正常終了]
+  final_join_2                                                                                                            [正常終了]
+  write orders                                                                                                       [不明なステップ]
+  RAW_CUSTOMERS (RAW_CUSTOMERS) 2                                                                                         [正常終了]
+  RAW_ORDERS (RAW_ORDERS) 2                                                                                               [正常終了]
+  stg_order                                                                                                               [正常終了]
+  customer_orders_first_order_and_number_of_orders                                                                        [正常終了]
+  ===================================================== 19 成功, 1 警告, 2 失敗 =====================================================
+  🎉dbtモデルへの変換が完了しました。
+
+describe
+******************************************************
+
+フローファイルの内容を解析し、統計情報を出力します
+
+.. code-block:: shell
+
+  $ prep2dbt describe -f /path/to/file.tfl
+
+オプション
+======================================================
+
+.. option:: -f, --flow-file 
+
+  変換するフローファイル（.tfl/.tflx）のパス。
+
+.. option:: -w, --work-dir   
+
+  作業ディレクトリパス。デフォルトはカレントディレクトリです。
+
+出力
+======================================================
+
+.. code-block:: shell
+
+  $ prep2dbt describe -f flow.tfl
+  🎉集計完了しました。ステップ単位の詳細は、outputs/result.csvを確認してください。
+  ノード数　　 : 22
+  エッジ数　　 : 24
+  入力ノード数 : 3
+  出力ノード数 : 2
+  深さ　　　　 : 8
+  幅　　　　　 : 4
+  密度　　　　 : 0.1039
+  平均次数　　 : 2.1818

docs/build/html/_sources/convert_subcommand/columns.rst.txt

@@ -0,0 +1,40 @@
+カラム定義の計算
+******************************************************
+
+グラフ化されたフローから、各ステップでのカラム定義が計算されます。
+
+カラム定義とは
+====================
+
+たとえば、以下のようにクリーニングステップで列名が変更されている場合を考えます。
+
+.. image:: ../images/convert/rename_cols.png
+  :width: 600px
+  :align: center
+
+この場合、各ステップではカラムは以下のような状態を持っていると言えます。
+
+.. image:: ../images/convert/rename_cols_definition.drawio.png
+  :width: 600px
+  :align: center
+
+このような、親から子に対して引き継がれ、子のもつ操作によって更新されていくカラムの状態を、 ``カラム定義`` と呼ぶことにします。
+
+計算方法
+====================
+
+グラフ化されたノードを、依存関係順に並び替え（トポロジカルソート）を行い、上流レイヤーから順番に計算し、結果を下流へ伝播させます。
+
+各ステップの種類ごとの計算ロジックは、:doc:`/converters/converters_index` を参照してください。
+
+カラム定義が計算できなかったとき
+==================================
+
+変換時、カラム定義の計算に失敗することがあります。
+
+たとえば、フローをTableau Prepで開いたとき、ネットワークやアクセス権限の問題などでデータソースが読み取れなかったとします。
+この状態でエクスポートしたフローの定義ファイルには、ソースのカラム情報が記録されないことがあります。
+このフローファイルを用いると、源泉データのカラムが不明のため、下流もカラム定義が計算できません。
+その他、本ツールでは変換仕様が未実装のステップを見つけたときにも、カラム定義の計算ができないため、不明として扱われます。
+
+基本的には、上流のカラム定義が不明だった場合には、その下流のカラム定義も不明として扱われます。

docs/build/html/_sources/convert_subcommand/convert_index.rst.txt

@@ -0,0 +1,12 @@
+dbtモデル変換
+######################################################
+
+.. toctree:: 
+    :maxdepth: 1
+
+    ./introduction
+    ./unzip_flow_file
+    ./graph
+    ./columns
+    ./sqls
+    ./implemented_features

docs/build/html/_sources/convert_subcommand/graph.rst.txt

@@ -0,0 +1,106 @@
+グラフへの変換
+******************************************************
+
+読み込まれたTableau Prepフローの定義情報は、
+内部では `NetworkX <https://networkx.org/>`_ の有向グラフ（DAG）に変換されます。
+
+変換方法
+========================================
+
+DAG変換は、フロー定義情報のJson構造が以下の通りになっていることを期待して動作します。
+
+.. code-block:: json
+    :caption: フロー定義情報（一部属性は省略）
+
+    {
+        "nodes" : {
+            "87818c7b-aea2-47c0-90ec-58638350bbc3" : {
+                "nodeType" : ".v1.LoadSql",
+                "name" : "RAW_PAYMENTS",
+                "id" : "87818c7b-aea2-47c0-90ec-58638350bbc3",
+                "nextNodes" : [ {
+                    "namespace" : "Default",
+                    "nextNodeId" : "46899811-b91a-4959-ad7f-fccb102760f1",
+                    "nextNamespace" : "Default"
+                } ],
+            },
+            "46899811-b91a-4959-ad7f-fccb102760f1" : {
+                "nodeType" : ".v2018_2_3.SuperTransform",
+                "name" : "stg_payment",
+                "id" : "46899811-b91a-4959-ad7f-fccb102760f1",
+                "nextNodes" : [ ],
+            }
+        }
+    }
+
+
+``nodes`` 属性配下の各ステップは、 ``id`` を持ちます。多くの場合でこれはフローの中でユニークになるようUUID形式で採番されています。
+
+さらに各ステップは、 ``nextNodes`` 属性に次のステップへの参照を含んでいます。
+よって、この ``nextNodes`` 属性から ``nextNodeId`` を読み取って、次のノードに対するエッジを張ることができます。
+
+.. image:: ../images/convert/next_node.drawio.png
+  :width: 600px
+  :align: center
+
+.. caution:: 
+
+    グループ化されたステップの場合、グループとステップの参照の仕方が異なります。そのため、グループ化されたステップではグラフへの変換が動作しません。
+
+    現バージョンでは、グループ化されたステップの変換はサポートできていないため、変換前にグループ化の解除を行ってから、ツールを使用してください。
+
+なお、 ``namespace`` 属性は、親が複数いる場合に、親を見分けるために使用されます。
+
+.. code-block:: json
+    :caption: 結合ステップの例
+
+    {
+        "355c32c3-1670-4e38-b30b-8390d27c9f31" : {
+            "nodeType" : ".v2018_2_3.SuperTransform",
+            "name" : "customer_payments",
+            "id" : "355c32c3-1670-4e38-b30b-8390d27c9f31",
+            "nextNodes" : [ {
+                "namespace" : "Default",
+                "nextNodeId" : "d7c4fbab-1c11-4e48-bea8-b9c4ab4fa19f",
+                "nextNamespace" : "Right"
+            } ],
+        },
+        "e7eb3a16-c537-405b-bc55-06be5246f6e0" : {
+            "nodeType" : ".v2018_2_3.SuperJoin",
+            "name" : "final_join_1",
+            "id" : "e7eb3a16-c537-405b-bc55-06be5246f6e0",
+            "nextNodes" : [ {
+                "namespace" : "Default",
+                "nextNodeId" : "d7c4fbab-1c11-4e48-bea8-b9c4ab4fa19f",
+                "nextNamespace" : "Left"
+            } ],
+        },
+        "d7c4fbab-1c11-4e48-bea8-b9c4ab4fa19f" : {
+            "nodeType" : ".v2018_2_3.SuperJoin",
+            "name" : "final_join_2",
+            "id" : "d7c4fbab-1c11-4e48-bea8-b9c4ab4fa19f",
+            "nextNodes" : [ ],
+            "actionNode" : {
+                "nodeType" : ".v1.SimpleJoin",
+                "name" : "結合 6",
+                "id" : "5f18418f-ba28-45ee-bf31-bc638d2c43f4",
+                "baseType" : "transform",
+                "nextNodes" : [ ],
+                "serialize" : false,
+                "description" : null,
+                "conditions" : [ {
+                "leftExpression" : "[CUSTOMER_ID-1]",
+                "rightExpression" : "[CUSTOMER_ID]",
+                "comparator" : "=="
+                } ],
+                "joinType" : "left"
+            }
+        },
+    }
+
+この結合ステップでは、親ステップに対してそれぞれ ``Left`` 、 ``Right`` とnamespaceが振られており、子の結合ステップがそれぞれを右側と左側どちらのテーブルとして扱うべきか示しています。
+
+.. image:: ../images/convert/next_node_joined.drawio.png
+  :width: 600px
+  :align: center
+

docs/build/html/_sources/convert_subcommand/implemented_features.rst.txt

@@ -0,0 +1,35 @@
+対応バージョン
+******************************************************
+
+Tableau Prepフロー機能のうち、以下機能は本ツールで変換仕様が定義済みです。
+
+もし以下にない機能を含む変換を自動で行いたい場合には、カスタムコンバーターを追加できます。
+詳細は :doc:`/develop_guide` を参照してください。
+
+- ステータスはコンバーターのテストレベルを示します。
+    - ベータ ： おそらく動作しますが、複数バージョンでフロー定義フォーマットを見比べることをしていないため、想定できていないフォーマットがまだあるかもしれません。
+    - 安定版 ： 2つ以上のTableau Prepバージョンで作られたフロー定義に対してテストされています。
+
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 機能名                        | 対応済みバージョン        | 変換定義のステータス | メモ                                                                   |
++===============================+===========================+======================+========================================================================+
+| 接続 (サーバー)               | .v1.LoadSql               | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 接続 (Tableau Server)         | .v2019_3_1.LoadSqlProxy   | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 接続 (CSV)                    | .v1.LoadCsv               | ベータ               |                                                                        |
+|                               |                           |                      |                                                                        |
+|                               | .v1.LoadCsvInputUnion     |                      |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 接続 (Excel)                  | .v1.LoadExcel             | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 集計 (SuperAggregate)         | .v2018_2_3.SuperAggregate | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 結合 (SuperJoin)              | .v2018_2_3.SuperJoin      | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| クリーニング (SuperTransform) | .v2018_2_3.SuperTransform | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| クリーニング (Container)      | .v1.Container             | ベータ               | 古いTableau Prepバージョンで定義されるクリーニングステップの仕様です。 |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+
+| 出力 (WriteToHyper)           | .v1.WriteToHyper          | ベータ               |                                                                        |
++-------------------------------+---------------------------+----------------------+------------------------------------------------------------------------+

docs/build/html/_sources/convert_subcommand/introduction.rst.txt

@@ -0,0 +1,10 @@
+導入
+******************************************************
+
+このツールでは、Tableau Prepのフローをdbtモデルに変換するため、以下の手順を実行します。
+
+- フローファイルを解凍し、含まれる定義情報を読み込む
+- フローをグラフに変換する
+- カラム定義を計算する
+- 各ステップの処理をSQLに変換する
+- SQLと、モデルの構成ファイル（yml）を書き出す