开发文档以外的部分初版写完了

py3env.sh

@@ -5,7 +5,7 @@ SCRIPT_DIR="$(dirname $0)";
 if [ ! -e "$SCRIPT_DIR/py3env/bin/pip3" ]; then
     virtualenv -p "$(which python3)" "$SCRIPT_DIR/py3env";
     export PATH=$SCRIPT_DIR/py3env/bin:$PATH;
-    pip3 install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark ;
+    pip3 install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark cloud_sptheme ;
     echo "#!/bin/bash
 export export PATH=$SCRIPT_DIR/py3env/bin:\$PATH;
     " > $SCRIPT_DIR/py3env/source.sh ;

source/conf.py

@@ -16,7 +16,8 @@
 import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-import sphinx_rtd_theme
+# import sphinx_rtd_theme
+import cloud_sptheme as csp
 from recommonmark.parser import CommonMarkParser
 
 # -- Project information -----------------------------------------------------
@@ -87,12 +88,19 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
+# html_theme = 'cloud'
+
+# set the theme path to point to cloud's theme data
+# html_theme_path = [csp.get_theme_dir()]
 
 # 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 = {}
+html_theme_options = { 
+    "roottarget": "index",
+    "logotarget": "_static/logo.png"
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

source/index.rst

@@ -68,10 +68,10 @@ xresloader文档
 
 .. toctree::
    :caption: 其他
-   
+
    about
 
 .. 
     * :ref:`genindex`
     * :ref:`modindex` 
-    * :ref:`search`
+    * :ref:`search`

source/sample/quick_start/sample-conf/sample.xml

@@ -2,7 +2,7 @@
 <root>
     <global>
         <work_dir desc="工作目录，相对于当前xml的目录，我们的Excel文件放在这里">.</work_dir>
-        <xresloader_path desc="指向前面下载的 转表工具-xresloader，相对于当前xml的目录">../xresloader/target/xresloader-1.4.2.jar</xresloader_path>
+        <xresloader_path desc="指向前面下载的 转表工具-xresloader，相对于当前xml的目录">../xresloader/target/xresloader-1.4.3.jar</xresloader_path>
 
         <proto desc="协议类型，-p选项">protobuf</proto>
         <output_type desc="输出类型，对饮-t选项，输出二进制">bin</output_type>

source/sample/quick_start/sample-data/role_upgrade_cfg.bin

@@ -1,6 +1,6 @@
 
 E
-1.4.21.4.2.20180317040504"$md5:7bbe88cca1eb23ebdce75b0e10b88b4a�N

+1.4.31.4.3.20180330221557"$md5:7bbe88cca1eb23ebdce75b0e10b88b4a�N

 �N� 2
 �N� d�N� �
�N� �
�N� �
�N� ��N� ��N	� ��N
 � ��N� �

source/sample/xresconv_conf.xml

@@ -3,7 +3,7 @@
     <include desc="可以包含其他文件配置，然后本文件里的配置将会覆盖或合并配置，相对于当前xml的目录">sample.xml</include>
     <global>
         <work_dir desc="工作目录，相对于当前xml的目录">../xresloader/sample</work_dir>
-        <xresloader_path desc="xresloader地址，相对于当前xml的目录">../target/xresloader-1.4.2.jar</xresloader_path>
+        <xresloader_path desc="xresloader地址，相对于当前xml的目录">../target/xresloader-1.4.3.jar</xresloader_path>
 
         <proto desc="协议类型，对应xresloader的-p选项">protobuf</proto>
         <output_type desc="输出类型，对应xresloader的-t选项">json</output_type>

source/users/faq.rst

@@ -68,7 +68,7 @@ Windows下控制台里执行执行会报文件编码错误？（java.nio.charset
 + 第二种: 在powershell里执行
 
 
-C++加载代码编译时出现xresloader符号重定义（multiple definition of `` com::owent::xresloader::pb::xresloader_XXX）``
+C++加载代码编译时出现xresloader符号重定义（multiple definition of ``com::owent::xresloader::pb::xresloader_XXX）``
 ---------------------------------------------------------------------------------------------------------------------
 pb_header.pb.cc 和 pb_header_v3.pb.cc 只能保留一个
 

source/users/output_format.rst

@@ -1,6 +1,8 @@
-数据的输出类型和数据加载
+数据输出和数据加载
 =============================================
 
+.. _xresloader sample: https://github.com/xresloader/xresloader/tree/master/sample
+
 所有输出的数据的结构都是按照 https://github.com/xresloader/xresloader/blob/master/header/pb_header_v3.proto 的 ``xresloader_datablocks`` 的结构。 ::
 
 > 转表功能和二进制数据读取的示例： https://github.com/xresloader/xresloader/tree/master/sample
@@ -143,7 +145,7 @@ Lua和Javacript的输出方式和输出设置有关，也很容易看懂，这
         EN_CT_DIAMOND              = 10101;
     }
 
-Lua代码目标:
+Lua目标代码（标准形式）:
 
 .. code-block:: lua
 
@@ -171,22 +173,56 @@ Lua代码目标:
 
     return const_res
 
-对于导出的代码，可以通过 ``--pretty 缩进数量`` 来设置格式化输出。
+对于一些特殊的Lua环境（比如Unity中）可能希望按Lua 5.1的方式加载模块，那么我们也可以使用特殊选项来更换导出方式，比如使用 ``--lua-module ProtoEnums.Kind`` 后输出如下:
+
+.. code-block:: lua
+
+    module("ProtoEnums.Kind", package.seeall)
+    -- this file is generated by xresloader, please don't edit it.
+
+    local const_res = {
+      game_const_config = {
+        EN_GCC_SCREEN_WIDTH = 1136,
+        EN_GCC_SCREEN_HEIGHT = 640,
+        EN_GCC_UNKNOWN = 0,
+        EN_GCC_CAMERA_OFFSET = 268,
+        EN_GCC_FORMULAR_TYPE_MASK = 10,
+        EN_GCC_LEVEL_LIMIT = 999,
+        EN_GCC_RESOURCE_MAX_LIMIT = 9999999,
+        EN_GCC_SOLDIER_TYPE_MASK = 100,
+        EN_GCC_PERCENT_BASE = 10000,
+        EN_GCC_RANDOM_RANGE_UNIT = 10,
+        EN_GCC_ACTIVITY_TYPE_MASK = 1000,
+      },
+      cost_type = {
+        EN_CT_DIAMOND = 10101,
+        EN_CT_MONEY = 10001,
+        EN_CT_UNKNOWN = 0,
+      },
+    }
+
+
+    game_const_config = const_res.game_const_config
+    cost_type = const_res.cost_type
+
+于导出的代码，可以通过 ``--pretty 缩进数量`` 来设置格式化输出，上面的输出使用的都是 ``--pretty 2`` 。
+
+其他语言和格式导出选项也类似上面的Lua的结构，具体请参考输出的文件内容加载。
 
 数据加载
 -----------------------------------------------
 
 前面小节我们大致展示了转出数据的结构，以此比较容易理解加载的方式。本小节则是对一些环境和语言的简单加载库。
 
-Step-6-1(推荐): 使用C++加载二进制数据
+方式-1(推荐): 使用C++加载二进制数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 此加载方式需要上面的 :ref:`output-format-export binary`
 
-在 :ref:`快速上手-Step-6.1: 使用读取库解析 <quick_start-load-with-libresloader>` 里我们已经给出了这种加载方式的具体使用，这里不再复述。
+在 :ref:`快速上手-方式.1: 使用读取库解析 <quick_start-load-with-libresloader>` 里我们已经给出了这种加载方式的具体使用，这里不再复述。
 这里提供的方式也支持protobuf的lite模式。
 
-Step-6-2(推荐): 使用lua-pbc加载二进制数据
+方式-2(推荐): 使用lua-pbc加载二进制数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 此加载方式需要上面的 :ref:`output-format-export binary`
@@ -252,22 +288,96 @@ Step-6-2(推荐): 使用lua-pbc加载二进制数据
 | pbc_config_manager:load_buffer_kv(协议名, 二进制, function(序号, 转出的lua table) return key的值 end, 别名) -- 读取key-value型数据接口
 | pbc_config_manager:load_buffer_kl(协议名, 二进制, function(序号, 转出的lua table) return key的值 end, 别名) -- 读取key-list型数据接口
 
-Step-6-3(推荐): 使用C#和DynamicMessage-net加载二进制数据
+方式-3(推荐): 使用C#和DynamicMessage-net加载二进制数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 此加载方式需要上面的 :ref:`output-format-export binary`
 
 为了方便Unity能够不依赖反射动态获取类型和读取配置，我们提供了 `DynamicMessage-net <https://github.com/xresloader/DynamicMessage-net>`_ 项目。
 这个项目依赖 `protobuf-net <https://github.com/mgravell/protobuf-net>`_ 的底层。 详见项目主页: https://github.com/xresloader/DynamicMessage-net
 
-Step-6-4(可选): 使用node.js加载javascript文本数据
+方式-4(可选): 加载msgpack文本数据
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+此加载方式需要上面的 :ref:`output-format-export msgpack`
+
+Msgpack的支持库语言和库很多，我们就不依依列举了。我们有一些python和node.js上的简单示例可以参见 https://github.com/xresloader/xresloader/tree/master/loader-binding/msgpack 。
+
+方式-5(可选): 使用node.js加载javascript文本数据
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 此加载方式需要上面的 :ref:`output-format-export text`
 
-https://github.com/xresloader/xresloader/tree/master/loader-binding/msgpack
+把配置输出javascript代码的时候，我们支持Node.js模式和AMD模式。
+
+比如，`xresloader sample`_ 中导出的 `role_cfg.n.js <https://github.com/xresloader/xresloader/blob/master/sample/proto_v3/role_cfg.n.js>`_ 。我们可以通过以下代码加载：
+
+.. code-block:: javascript
 
-Step-6-5(可选): 使用lua加载导出的枚举类型
+    const role_cfg_block = require('./role_cfg.n');
+    const role_cfg_header = role_cfg_block.role_cfg_header; // 数据头信息，header
+    const role_cfg = role_cfg_block.role_cfg;               // 数据集合，Ayyar类型
+
+    // 读取数据
+    console.log(`we got ${role_cfg_header.count} rows, data version: ${role_cfg_header.data_ver}`);
+
+    for (const i in role_cfg) {
+        if (role_cfg[i].id === 10001) {
+            console.log('================= print data with id = 10001 =================');
+            console.log(role_cfg[i]);
+        }
+    }
+
+详见： https://github.com/xresloader/xresloader/tree/master/loader-binding/javascript
+
+方式-6(可选): 使用lua加载导出的枚举类型
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-此加载方式需要上面的 :ref:`output-format-export enum`
+上面 :ref:`output-format-export enum` 提到，我们可以把一些枚举类型放在proto文件里统一维护，然后不同的使用者导出成不同目标语言的代码。
+而对于protobuf没有原生支持的语言，我们支持导出 ``lua`` 、 ``javascript`` 、 ``xml`` 或 ``json`` 辅助我们使用。
+
+比如上面两种Lua导出，我们可以直接通过Lua脚本加载：
+
+.. code-block:: lua
+
+    local const_enum = require('kind_const')
+
+    print('game_const_config.EN_GCC_PERCENT_BASE = ' .. const_enum.game_const_config.EN_GCC_PERCENT_BASE)
+
+    function dump_all_enum (pv, ident) 
+        for k, v in pairs(pv) do
+            if string.sub(k, 0, 1) ~= '_' and 'table' == type(v) then
+                print(string.format('%s%s = {', ident, k))
+                dump_all_enum(v, ident .. '  ')
+                print(string.format('%s}', ident))
+            else
+                print(string.format('%s%s = %s,', ident, k, v))
+            end
+        end
+    end
+
+    dump_all_enum(const_enum, '')
+
+让我们再来看看Lua 5.1的module模式的枚举类型加载：
+
+.. code-block:: lua
+
+    require('kind_const_module')
+
+    print('game_const_config.EN_GCC_PERCENT_BASE = ' .. ProtoEnums.Kind.game_const_config.EN_GCC_PERCENT_BASE)
+
+    function dump_all_enum (pv, ident) 
+        for k, v in pairs(pv) do
+            if string.sub(k, 0, 1) ~= '_' and 'table' == type(v) then
+                print(string.format('%s%s = {', ident, k))
+                dump_all_enum(v, ident .. '  ')
+                print(string.format('%s}', ident))
+            else
+                print(string.format('%s%s = %s,', ident, k, v))
+            end
+        end
+    end
+
+    dump_all_enum(ProtoEnums.Kind, '')
+
+其他语言和格式的加载请参考输出文件。

source/users/quick_start.rst

@@ -114,7 +114,7 @@ Step-5: 运行转表工具
 
     * target (下载的xresloader所在目录)
 
-      * xresloader-1.4.2.jar
+      * xresloader-1.4.3.jar
 
   * xresconv-cli (命令行转表工具所在目录)
 
@@ -213,8 +213,8 @@ Step-6.2: 手动解析
 .. code-block:: bash
 
     ========================
-    data header: xres_ver: "1.4.2"
-    data_ver: "1.4.2.20180317040504"
+    data header: xres_ver: "1.4.3"
+    data_ver: "1.4.3.20180317040504"
     count: 11
     hash_code: "md5:7bbe88cca1eb23ebdce75b0e10b88b4a"