fix document for xresloader 2.5.0

.vscode/settings.json

@@ -2,7 +2,6 @@
     "editor.fontFamily": "Noto Sans Mono CJK SC, YaHei Consolas Hybrid,Source Code Pro,Microsoft YaHei,Consolas,serif",
     "editor.fontSize": 16,
     "restructuredtext.builtDocumentationPath": "${workspaceRoot}/build/html",
-    "restructuredtext.confPath": "${workspaceFolder}\\source",
     "restructuredtext.linter.extraArgs": [],
     "files.associations": {
         "*.ejs": "html",
@@ -12,5 +11,12 @@
         "vector": "cpp",
         "xstring": "cpp",
         "xutility": "cpp"
-    }
+    },
+    "python.linting.pylintPath": "${workspaceFolder}/py3env/bin/pylint",
+    "python.linting.flake8Path": "${workspaceFolder}/py3env/bin/flake8",
+    "python.formatting.yapfPath": "${workspaceFolder}/py3env/bin/yapf",
+    "python.formatting.autopep8Path": "${workspaceFolder}/py3env/bin/autopep8",
+    "python.linting.pep8Path": "${workspaceFolder}/py3env/bin/pep8",
+    "python.linting.pydocstylePath": "${workspaceFolder}/py3env/bin/pydocstyle",
+    "python.pythonPath": "${workspaceFolder}/py3env/bin/python"
 }

py3env.sh

@@ -3,17 +3,23 @@
 SCRIPT_DIR="$(dirname "$0")";
 SCRIPT_DIR="$(cd "$SCRIPT_DIR" && pwd)";
 
+# PATH for editor ${workspaceFolder}/py3env/bin
+
 if [ ! -e "$SCRIPT_DIR/py3env/bin/pip3" ]; then
+    python3 -m pip install virtualenv;
     python3 -m virtualenv -p "$(which python3)" "$SCRIPT_DIR/py3env";
-    export PATH=$SCRIPT_DIR/py3env/bin:$PATH ;
-    pip install --upgrade pip setuptools ;
-    pip install --upgrade -r "$SCRIPT_DIR/requirements.txt" ;
 fi
 
+export PATH=$SCRIPT_DIR/py3env/bin:$PATH ;
+pip install --upgrade -r "$SCRIPT_DIR/requirements-vscode.txt" ;
+pip install --upgrade -r "$SCRIPT_DIR/requirements.txt" ;
+
 echo "#!/bin/bash
 
 export PATH=\"$SCRIPT_DIR/py3env/bin:\$PATH\" ;
 
 \"\$@\"
-    " > $SCRIPT_DIR/py3env/source.sh ;
+    " > "$SCRIPT_DIR/py3env/source.sh" ;
+
+chmod +x "$SCRIPT_DIR/py3env/source.sh" ;
 

requirements-vscode.txt

@@ -0,0 +1,8 @@
+pydocstyle>=4.0.1
+pep8>=1.7.1
+autopep8>=1.4.4
+yapf>=0.27.0
+pylint>=2.3.1
+flake8>=3.7.8
+
+# PATH for editor ${workspaceFolder}/py3env/bin/

requirements.txt

@@ -1,8 +1,9 @@
+setuptools>=41.2.0
 sphinx>=1.7.2
 sphinx-autobuild>=0.7.1
 sphinx-rtd-theme>=0.3.0
 recommonmark>=0.4.0
-cloud-sptheme>=1.9.4
+sphinx-readable-theme>=1.3.0
 readthedocs-sphinx-ext>=0.5.9
 # NOTE: switched to custom branch until https://github.com/dreamhost/sphinxcontrib-fulltoc/issues/10 is fixed
 # sphinxcontrib-fulltoc>=1.2.0

source/_static/css/custom.css

@@ -1,3 +1,39 @@
-body li, body dd, body p {
+body li,
+body dd,
+body p {
     text-align: left !important;
 }
+
+/************ patch readable.css for hihger resolution **************/
+div.document {
+    max-width: 1440px;
+}
+
+div.body {
+    max-width: 1210px;
+}
+
+div.sphinxsidebar {
+    width: 320px;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 320px;
+}
+
+/* copy from readable.css */
+
+@media screen and (max-width: 870px) {
+
+    div.document {
+        width: auto;
+    }
+
+    div.bodywrapper {
+        margin: 0;
+    }
+
+    div.sphinxsidebar {
+        width: auto;
+    }
+}

source/conf.py

@@ -17,7 +17,7 @@
 # sys.path.insert(0, os.path.abspath('.'))
 
 # import sphinx_rtd_theme
-import cloud_sptheme as csp
+import sphinx_readable_theme
 from recommonmark.parser import CommonMarkParser
 
 # -- Project information -----------------------------------------------------
@@ -102,19 +102,18 @@
 # a list of builtin themes.
 #
 # html_theme = 'sphinx_rtd_theme'
-html_theme = 'cloud'
+html_theme = 'readable'
 
 # set the theme path to point to cloud's theme data
-html_theme_path = [csp.get_theme_dir()]
+html_theme_path = [sphinx_readable_theme.get_html_theme_path()] # [csp.get_theme_dir()]
+
+html_logo = "_static/logo.png"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 html_theme_options = { 
-    "roottarget": "index",
-    "logotarget": "_static/logo.png",
-    "externalrefs": False
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -132,8 +131,6 @@
 #
 # html_sidebars = {}
 
-html_logo = "_static/logo.png"
-
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.

source/sample/quick_start/sample-conf/kind.proto

@@ -1,13 +1,18 @@
 syntax = "proto3";
 
 import "xresloader.proto";
-import "xresloader_ue.proto";
+
+enum cost_type {
+  EN_CT_UNKNOWN = 0;
+  EN_CT_MONEY   = 10001 [(org.xresloader.enum_alias) = "金币"];
+  EN_CT_DIAMOND = 10101 [(org.xresloader.enum_alias) = "钻石"];
+}
 
 message role_upgrade_cfg {
   uint32 Id = 1;
   uint32 Level = 2;
   uint32 CostType = 3 [
-    (org.xresloader.verifier) = "cost_type",
+    (org.xresloader.verifier) = "cost_type", // 这里等同于在Excel中使用 @cost_type 标识
     (org.xresloader.field_description) = "Refer to cost_type"
   ];
   int32 CostValue = 4;

source/users/advance_usage.rst

@@ -8,15 +8,15 @@
 .. _xresloader header extensions v2: https://github.com/xresloader/xresloader/tree/master/header/extensions/v2
 .. _xresloader header extensions v3: https://github.com/xresloader/xresloader/tree/master/header/extensions/v3
 
-元数据替换（别名/宏）
+文本替换（别名/宏）
 ---------------------------------------------
 
 为了便于理解，我们支持配置一组别名的表。在 ``MacroSource`` 中，主配置为文件名，次配置为表明，补充配置为Key-Value的开始行号和列号。比如：
 
 +-------------------+--------------------------------+-----------------------+----------------+-----------+----------------------------------------------------+ 
 | 字段              | 简介                           | 主配置                | 次配置         | 补充配置  | 说明                                               |
 +===================+================================+=======================+================+===========+====================================================+
-| MacroSource       | 元数据数据源(文件路径,表名)    | 资源转换示例.xlsx     | macro          | 2,1       | 次配置为表名，补充配置为数据起始位置(行号, 列号)   |
+| MacroSource       | 文本宏数据源(文件路径,表名)    | 资源转换示例.xlsx     | macro          | 2,1       | 次配置为表名，补充配置为数据起始位置(行号, 列号)   |
 +-------------------+--------------------------------+-----------------------+----------------+-----------+----------------------------------------------------+
 
 这时候我们会认为在文件 ``资源转换示例.xlsx`` ， ``macro`` 表中。从第 ``2`` 行开始，第 ``1`` 列为别名的Key，第 ``2`` 列为别名的Value。
@@ -52,7 +52,7 @@
 +-----------+---------+-------------+--------------------------------+
 |   10001   | 1       |             |                                |
 +-----------+---------+-------------+--------------------------------+
-|   10001   | 2       | 1001        | 50                             |
+|   10001   | 2       | 10001       | 50                             |
 +-----------+---------+-------------+--------------------------------+
 
 上面这个表，如果 ``消耗值`` 这一列出现了[0, 1000]和[2000-3000]以外的值，转表工具会转表不通过并予以提示。
@@ -95,40 +95,106 @@ Protobuf 插件支持
 
 项目中可以导入 `xresloader header extensions`_ 目录， 然后通过导入 `xresloader header extensions v2`_ 或 `xresloader header extensions v3`_ 中的相应proto文件，就可以获得额外的插件扩展支持。
 
+> 注意: 使用插件功能时　生成pb的时候也要导入插件的proto文件和protobuf官方include目录里的 google/protobuf/descriptor.proto 文件。
+
 Protobuf插件 - Message插件
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-+----------------------------------+------------------------------------------------------------------+
-|            插件名称              |                   插件功能                                       |
-+==================================+==================================================================+
-| org.xresloader.msg_description   | 消息体描述信息，会写入输出的header中和代码中                     |
-+----------------------------------+------------------------------------------------------------------+
-|    org.xresloader.ue.helper      |         生成UE Utility代码的类名后缀                             |
-+----------------------------------+------------------------------------------------------------------+
-| org.xresloader.ue.not_data_table | 生成UE Utility代码时，不生产加载代码，这用于带name字段的依赖类型 |
-+----------------------------------+------------------------------------------------------------------+
++----------------------------------+---------+------------------------------------------------------------------+
+|            插件名称              |   类型  |                   插件功能                                       |
++==================================+=========+==================================================================+
+| org.xresloader.msg_description   |  string | 消息体描述信息，会写入输出的header中和代码中                     |
++----------------------------------+---------+------------------------------------------------------------------+
+|    org.xresloader.ue.helper      |  string |         生成UE Utility代码的类名后缀                             |
++----------------------------------+---------+------------------------------------------------------------------+
+| org.xresloader.ue.not_data_table |   bool  | 生成UE Utility代码时，不生产加载代码，这用于带name字段的依赖类型 |
++----------------------------------+---------+------------------------------------------------------------------+
 
 比如 `xresloader sample proto_v3 kind.proto`_ 里， ``arr_in_arr_cfg`` 配置了相关字段，会影响到一些输出。
 
 Protobuf插件 - Field插件
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-+--------------------------------------+----------------------------------------------------------------------------------------------------------------------+
-|             插件名称                 |                                                      插件功能                                                        |
-+======================================+======================================================================================================================+
-| org.xresloader.field_description     |                                     字段描述信息，会写入输出的header中和代码中                                       |
-+--------------------------------------+----------------------------------------------------------------------------------------------------------------------+
-|     org.xresloader.verifier          |                                     字段描述信息，会写入输出的header中和代码中                                       |
-+--------------------------------------+----------------------------------------------------------------------------------------------------------------------+
-|    org.xresloader.ue.key_tag         |                  生成UE代码时，如果需要支持多个Key组合成一个Name，用这个字段指定系数（必须大于0）                    |
-+--------------------------------------+----------------------------------------------------------------------------------------------------------------------+
-|   org.xresloader.ue.ue_type_name     | 生成UE代码时，如果指定了这个字段，那么生成的字段类型将是 ```TSoftObjectPtr<ue_type_name>``` , 并且支持蓝图中直接引用 |
-+--------------------------------------+----------------------------------------------------------------------------------------------------------------------+
-|   org.xresloader.ue.ue_type_is_class | 生成UE代码时，如果这个字段为true，那么生成的字段类型将是 ```TSoftClassPtr<ue_type_name>``` , 并且支持蓝图中直接引用  |
-+--------------------------------------+----------------------------------------------------------------------------------------------------------------------+
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|             插件名称                 |   类型  |                                                      插件功能                                                        |
++======================================+=========+======================================================================================================================+
+| org.xresloader.field_description     |  string |                                     字段描述信息，会写入输出的header中和代码中                                       |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|     org.xresloader.verifier          |  string |                                     字段描述信息，会写入输出的header中和代码中                                       |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|    org.xresloader.field_alias        |  string |                                     字段别名，可用于验证器和Excel中直接填别名                                        |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|    org.xresloader.field_ratio        |  int32  |     数值放大倍数，``转出数值=Excel内数值*field_ratio``。比如设为1000时，如果Excel里填的是1.05，转出的数据是　1050　　|
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|    org.xresloader.ue.key_tag         |  int32  |                  生成UE代码时，如果需要支持多个Key组合成一个Name，用这个字段指定系数（必须大于0）                    |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|   org.xresloader.ue.ue_type_name     |  string | 生成UE代码时，如果指定了这个字段，那么生成的字段类型将是 ```TSoftObjectPtr<ue_type_name>``` , 并且支持蓝图中直接引用 |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|   org.xresloader.ue.ue_type_is_class |   bool  | 生成UE代码时，如果这个字段为true，那么生成的字段类型将是 ```TSoftClassPtr<ue_type_name>``` , 并且支持蓝图中直接引用  |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+
+比如我们定义单位属性的proto如下：
+
+.. code-block:: proto
+
+    import "xresloader.proto";
+
+    message unit_attribute {
+        int32 hp           = 1 [(org.xresloader.field_alias) = "生命"];
+        int32 mp           = 2 [(org.xresloader.field_alias) = "魔力"];
+        int32 power        = 3 [(org.xresloader.field_alias) = "力量"];
+    }
+
+    message skill_effect {
+        int32 id           = 1;
+        int32 level        = 2;
+        int32 func_type    = 3;
+        int32 attr_type    = 4;
+        int32 value        = 5;
+    }
+
+然后我们可以在Excel表中使用别名：
+
++-----------+---------+-------------+--------------------------+-----------+
+|  技能ID   |   等级  |   功能类别  | 属性                     |   值      |
++===========+=========+=============+==========================+===========+
+|   id      | level   | func_type   | attr_type@unit_attribute | value     |
++-----------+---------+-------------+--------------------------+-----------+
+|   20001   | 1       |             | **生命**                 | 100       |
++-----------+---------+-------------+--------------------------+-----------+
+|   20001   | 2       | 1001        | **生命**                 | 200       |
++-----------+---------+-------------+--------------------------+-----------+
+
+
+Protobuf插件 - EnumValue插件
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|             插件名称                 |   类型  |                                                      插件功能                                                        |
++======================================+=========+======================================================================================================================+
+| org.xresloader.enumv_description     |  string |                                   枚举值描述信息，会写入输出的header中和代码中                                       |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
+|    org.xresloader.enum_alias         |  string |                                   枚举值别名，可用于验证器和Excel中直接填别名                                        |
++--------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------+
 
 比如 `xresloader sample proto_v3 kind.proto`_ 里， ``role_upgrade_cfg`` 内的 ``CostType`` 这一列配置验证器引射到协议的 ``cost_type`` 和 协议描述字段。
 
+.. literalinclude:: ../sample/quick_start/sample-conf/kind.proto
+    :language: proto
+    :encoding: utf-8
+
+然后，我们就可以按如下方式配消耗类型:
+
++-----------+---------+-------------+--------------------------------+
+|  角色ID   |   等级  |   货币类别  |   消耗值                       |
++===========+=========+=============+================================+
+|   Id      | Level   | CostType    | CostValue@0-1000\|2000-3000    |
++-----------+---------+-------------+--------------------------------+
+|   10001   | 1       | EN_CT_MONEY | 10                             |
++-----------+---------+-------------+--------------------------------+
+|   10001   | 2       | **金币**    | 50                             |
++-----------+---------+-------------+--------------------------------+
+
 仅导出部分字段
 ---------------------------------------------