Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@owent
owent committed Apr 29, 2020
1 parent 7157cfd commit 0a85a5e
Show file tree
Hide file tree
Showing 6 changed files with 135 additions and 18 deletions.
2 changes: 1 addition & 1 deletion LICENSE.txt
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
The MIT License (MIT)

Copyright (c) 2019 OWenT
Copyright (c) 2020 OWenT

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
6 changes: 3 additions & 3 deletions requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
setuptools>=41.2.0
recommonmark>=0.6.0
sphinx>=2.2.0
sphinx>=3.0.3
sphinx-autobuild>=0.7.1
sphinx-rtd-theme>=0.3.0
sphinx-rtd-theme>=0.4.3
sphinx-readable-theme>=1.3.0
readthedocs-sphinx-ext>=0.5.9
readthedocs-sphinx-ext>=1.0.3
sphinx-markdown>=1.0.2
# NOTE: switched to custom branch until https://github.com/dreamhost/sphinxcontrib-fulltoc/issues/10 is fixed
# sphinxcontrib-fulltoc>=1.2.0
Expand Down
24 changes: 14 additions & 10 deletions source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ xresloader文档
* 完整支持协议结构，包括嵌套结构和数组嵌套
* 同时支持protobuf proto v2 和 proto v3
* 支持导出proto枚举值到lua/javascript代码和json/xml数据
* 支持导出proto描述信息值到lua/javascript代码和json/xml数据（支持自定义插件，方便用户根据proto描述自定义反射功能）
* 支持导出 UnrealEngine 支持的json或csv格式，支持自动生成和导出 UnrealEngine 的 ``DataTable`` 加载代码
* 支持别名表，用于给数据内容使用一个易读的名字
* 支持验证器，可以在数据里直接填写proto字段名或枚举名，或者验证填入数据的是否有效
Expand All @@ -28,29 +29,32 @@ xresloader文档
+--------------------+---------------------------------------------+
| 构建环境 | 构建状态 |
+====================+=============================================+
| `xresloader`_ | Linux (OpenJDK 8): |xresloader-trivis| |
| `xresloader`_ | Linux (OpenJDK 8): |xresloader-ci| |
+--------------------+---------------------------------------------+
| `xresconv-cli`_ | 直接下载发布包即可，无需构建打包 |
+--------------------+---------------------------------------------+
| `xresconv-gui`_ | Windows: |xresconv-gui-appveyor| |
| | macOS&Linux: |xresconv-gui-trivis| |
| `xresconv-gui`_ | |xresconv-gui-ci| |
+--------------------+---------------------------------------------+
| 文档 | |xresloader-docs| |
+--------------------+---------------------------------------------+

.. |xresloader-trivis| image:: https://travis-ci.org/xresloader/xresloader.svg?branch=master
.. |xresloader-ci| image:: https://github.com/xresloader/xresloader/workflows/Master%20Building/badge.svg
:alt: Build Status
:target: https://travis-ci.org/xresloader/xresloader
.. |xresconv-gui-appveyor| image:: https://ci.appveyor.com/api/projects/status/jla48prtf6brkgnf?svg=true
:target: https://github.com/xresloader/xresloader/actions?query=workflow%3A%22Master+Building%22
.. |xresconv-gui-ci| image:: https://github.com/xresloader/xresconv-gui/workflows/build/badge.svg
:alt: Build Status
:target: https://ci.appveyor.com/project/owt5008137/xresconv-gui
.. |xresconv-gui-trivis| image:: https://api.travis-ci.org/xresloader/xresconv-gui.svg?branch=master
:alt: Build Status
:target: https://travis-ci.org/xresloader/xresconv-gui
:target: https://github.com/xresloader/xresconv-gui/actions?query=workflow%3Abuild
.. |xresloader-docs| image:: https://readthedocs.org/projects/xresloader-docs/badge/?version=latest
:alt: Documentation Status
:target: https://readthedocs.org/projects/xresloader-docs/

.. image:: https://img.shields.io/github/v/release/xresloader/xresloader
.. image:: https://img.shields.io/github/languages/code-size/xresloader/xresloader
.. image:: https://img.shields.io/github/repo-size/xresloader/xresloader
.. image:: https://img.shields.io/github/downloads/xresloader/xresloader/total
.. image:: https://img.shields.io/github/forks/xresloader/xresloader?style=social
.. image:: https://img.shields.io/github/stars/xresloader/xresloader?style=social

.. _xresloader: https://github.com/xresloader
.. _xresloader-core: https://github.com/xresloader/xresloader
.. _xresconv-cli: https://github.com/xresloader/xresconv-cli
Expand Down
3 changes: 2 additions & 1 deletion source/sample/xresconv_conf.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.3.jar</xresloader_path>
<xresloader_path desc="xresloader地址，相对于当前xml的目录">../target/xresloader-2.7.1.jar</xresloader_path>

<proto desc="协议类型，对应xresloader的-p选项">protobuf</proto>
<output_type desc="输出类型，-t选项，支持多个同时配置多种输出">bin</output_type>
Expand Down Expand Up @@ -101,6 +101,7 @@
</on_before_convert>
<on_after_convert type="text/javascript" timeout="60000" description="事件执行结束必须调用resolve(value)或reject(reason)函数，以触发进行下一步">
// 同上
resolve();
</on_after_convert>
</gui>

Expand Down
116 changes: 113 additions & 3 deletions source/users/output_format.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,10 +159,15 @@ xresloader从2.0.0版本开始支持导出UE所支持的CSV或者JSON格式数
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

对应 ``-c`` 然后可以使用 ``-t json`` 、 ``-t xml`` 、 ``-t lua`` 、 ``-t js`` 、 ``-t ue-csv`` 、 ``-t ue-json`` 来指定按哪种方式输出枚举量。
比如把protobuf协议里的枚举输出成Lua代码，proto文件：

.. _output-format-export enum or options of proto file:

比如把protobuf协议里的枚举输出成Lua代码，``kind.proto`` 文件：

.. code-block:: proto
import "xresloader.proto";
// 常量类型
enum game_const_config {
option allow_alias = true;
Expand All @@ -184,8 +189,20 @@ xresloader从2.0.0版本开始支持导出UE所支持的CSV或者JSON格式数
// 货币类型
enum cost_type {
EN_CT_UNKNOWN = 0;
EN_CT_MONEY = 10001;
EN_CT_DIAMOND = 10101;
EN_CT_MONEY = 10001 [(org.xresloader.enum_alias) = "金币"];
EN_CT_DIAMOND = 10101 [(org.xresloader.enum_alias) = "钻石"];
}
// 这个message用于示例下面导出协议描述，对导出枚举数据无意义
message role_upgrade_cfg {
option (org.xresloader.ue.helper) = "helper";
option (org.xresloader.msg_description) = "Test role_upgrade_cfg with multi keys";
uint32 Id = 1 [ (org.xresloader.ue.key_tag) = 1000 ];
uint32 Level = 2 [ (org.xresloader.ue.key_tag) = 1 ];
uint32 CostType = 3 [ (org.xresloader.verifier) = "cost_type", (org.xresloader.field_description) = "Refer to cost_type" ];
int32 CostValue = 4;
int32 ScoreAdd = 5;
}
Lua目标代码（标准形式）:
Expand Down Expand Up @@ -252,6 +269,99 @@ Lua目标代码（标准形式）:

其他语言和格式导出选项也类似上面的Lua的结构，具体请参考输出的文件内容加载。

导出协议描述成代码 (可选)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

对应 ``-i`` 然后可以使用 ``-t json`` 、 ``-t xml`` 、 ``-t lua`` 、 ``-t js`` 、 ``-t ue-csv`` 、 ``-t ue-json`` 来指定按哪种方式输出枚举量。
比如把上述protobuf协议里的描述输出成Lua代码，协议文件见 :ref:`kind.proto <output-format-export enum or options of proto file>`

Lua目标代码（标准形式）:

.. code-block:: lua
-- this file is generated by xresloader, please don't edit it.
local const_res = {
files = {
{
enum_type = {
cost_type = {
name = "cost_type",
value = {
EN_CT_DIAMOND = {
name = "EN_CT_DIAMOND",
number = 10101,
options = {
enum_alias = "钻石",
},
},
EN_CT_MONEY = {
name = "EN_CT_MONEY",
number = 10001,
options = {
enum_alias = "金币",
},
},
},
},
game_const_config = {
name = "game_const_config",
options = {
allow_alias = true,
},
},
},
message_type = {
role_upgrade_cfg = {
field = {
CostType = {
name = "CostType",
number = 3,
options = {
field_description = "Refer to cost_type",
verifier = "cost_type",
},
type_name = "UINT32",
},
Id = {
name = "Id",
number = 1,
options = {
key_tag = 1000,
},
type_name = "UINT32",
},
Level = {
name = "Level",
number = 2,
options = {
key_tag = 1,
},
type_name = "UINT32",
},
},
name = "role_upgrade_cfg",
options = {
helper = "helper",
msg_description = "Test role_upgrade_cfg with multi keys",
},
},
},
name = "kind.proto",
package = "",
path = "kind.proto",
},
},
}
return const_res
同样,对于一些特殊的Lua环境（比如Unity中）可能希望按Lua 5.1的方式加载模块，那么我们也可以使用特殊选项来更换导出方式，比如使用 ``--lua-module ProtoOptions.Kind`` 。
输出的代码或文本同样可以通过 ``--pretty 缩进数量`` 来设置格式化输出，上面的输出使用的都是 ``--pretty 2`` 。
`xresloader sample`_ 中的 ``proto_v3/kind_option.js`` , ``proto_v3/kind_option.lua`` , ``proto_v3/kind_option.mod.lua`` 或 中的 ``proto_v2/kind_option.js`` , ``proto_v2/kind_option.lua`` , ``proto_v2/kind_option.mod.lua`` 有更多的示例。

其他语言和格式导出选项也类似上面的Lua的结构，具体请参考输出的文件内容加载。

.. _output-format-proto v2 and proto v3:

Proto v2和Proto v3
Expand Down
2 changes: 2 additions & 0 deletions source/users/xresloader_core.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,8 @@ xresloader-可用参数列表
.. code-block:: bash
echo '
-t lua -p protobuf -o '$proto_dir' -f '$proto_dir/kind.pb' --pretty 2 -i kind.desc.lua
-t json -p protobuf -o '$proto_dir' -f '$proto_dir/kind.pb' --pretty 2 -i kind.desc.json
-t json -p protobuf -o '$proto_dir' -f '$proto_dir/kind.pb' -s '$XLSX_FILE' -m scheme_kind -n "/(?i)\.bin$/\.json/"
-t xml -p protobuf -o '$proto_dir' -f '$proto_dir/kind.pb' -s '$XLSX_FILE' -m scheme_kind -n "/(?i)\.bin$/\.xml/"
-t msgpack -p protobuf -o '$proto_dir' -f '$proto_dir/kind.pb' -s '$XLSX_FILE' -m scheme_kind -n "/(?i)\.bin$/\.msgpack.bin/"
Expand Down

0 comments on commit 0a85a5e

Please sign in to comment.