调整主题和样式，一会看看改点style

py3env.sh

@@ -5,7 +5,8 @@ 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 cloud_sptheme ;
+    pip install --upgrade pip setuptools ;
+    pip install --upgrade -r "$SCRIPT_DIR/requirements.txt" ;
     echo "#!/bin/bash
 export export PATH=$SCRIPT_DIR/py3env/bin:\$PATH;
     " > $SCRIPT_DIR/py3env/source.sh ;

requirements.txt

@@ -0,0 +1,7 @@
+sphinx>=1.7.2
+sphinx-autobuild>=0.7.1
+sphinx-rtd-theme>=0.3.0
+recommonmark>=0.4.0
+cloud-sptheme>=1.9.4
+readthedocs-sphinx-ext>=0.5.9
+sphinxcontrib-fulltoc>=1.2.0

source/conf.py

@@ -16,8 +16,8 @@
 import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-import sphinx_rtd_theme
-# import cloud_sptheme as csp
+# import sphinx_rtd_theme
+import cloud_sptheme as csp
 from recommonmark.parser import CommonMarkParser
 
 # -- Project information -----------------------------------------------------
@@ -42,12 +42,22 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    # standard sphinx extensions
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
     'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
+
+    # 3rd party extensions
+    'sphinxcontrib.fulltoc',
+
+    # cloud's extensions
+    'cloud_sptheme.ext.autodoc_sections',
+    'cloud_sptheme.ext.relbar_links',
+    'cloud_sptheme.ext.escaped_samp_literals',
+    'cloud_sptheme.ext.issue_tracker',
+    'cloud_sptheme.ext.table_styling',
+    # 'cloud_sptheme.ext.role_index',  # NOTE: used only to provide example role index
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -87,8 +97,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
-# html_theme = 'cloud'
+# 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()]
@@ -97,10 +107,10 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = { 
-#     "roottarget": "index",
-#     "logotarget": "_static/logo.png"
-# }
+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,
@@ -117,12 +127,18 @@
 #
 # html_sidebars = {}
 
+html_logo = "_static/logo.png"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'xresloader-documentdoc'
+htmlhelp_basename = 'xresloader-document'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+html_use_smartypants = True
 
+html_sidebars = {'**': ['searchbox.html', 'globaltoc.html']}
 
 # -- Options for LaTeX output ------------------------------------------------
 
@@ -206,4 +222,6 @@
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+todo_include_todos = True
+keep_warnings = True
+issue_tracker_url = "gh:xresloader/xresloader"

source/index.rst

@@ -1,8 +1,3 @@
-.. xresloader-document documentation master file, created by
-   sphinx-quickstart on Tue Feb 27 14:29:08 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 xresloader文档
 ===============================================
 
@@ -17,10 +12,12 @@ xresloader文档
 |                    构建环境                  |                               Linux (Oracle JDK 8)                                   |
 +==============================================+======================================================================================+
 |         `xresloader`_ 当前构建状态           | .. image:: https://travis-ci.org/xresloader/xresloader.svg?branch=master             |
-|                                              |    :alt: Build Status                                                                |
+|                                              |    :alt: Build Status                                                                | 
+|                                              |    :target: https://travis-ci.org/xresloader/xresloader                              |
 +----------------------------------------------+--------------------------------------------------------------------------------------+
 |                  文档构建状态                | .. image:: https://readthedocs.org/projects/xresloader-docs/badge/?version=latest    |
 |                                              |    :alt: Documentation Status                                                        |
+|                                              |    :target: https://readthedocs.org/projects/xresloader-docs/                        |
 +----------------------------------------------+--------------------------------------------------------------------------------------+
 
 .. _xresloader: https://github.com/xresloader

source/users/faq.rst

@@ -82,3 +82,13 @@ C++加载代码编译时出现xresloader版本检查错误
 具体表现为编译时输出 ``This file was generated by an older version of protoc ...`` 或 ``This file was generated by a newer version of protoc ...`` 。
 
 这是因为protoc版本和目前所用的protobuf版本不一致，请尝试重新用目前所用的protoc根据配置的proto文件和header目录中的 ``pb_header_v3.proto`` 或 ``pb_header.proto`` 重新生成c++代码文件。
+
+
+proto v2版本API解析repeated的整数或浮点数类型字段失败(Wire Type)
+----------------------------------------------------------------------------------------------------------------
+
+我们转表默认使用的是proto v3模式，几乎所有编码规则都是向前兼容到proto v2的，但是也有一个例外，就是repeated的数值类型。
+
+repeated的数值类型在proto v2里默认是 ``[ packed = false ]`` 而在proto v3里是 ``[ packed = true ]`` 。解决方法是显式指定打包方式。
+
+详见 :ref:`output-format-proto v2 and proto v3` 。

source/users/output_format.rst

@@ -217,10 +217,12 @@ Proto v2和Proto v3
 
 详见： https://developers.google.com/protocol-buffers/docs/proto3#specifying-field-rules
 
-简单地说，就是proto v2里数字类型的 ``repeated`` 字段默认是 ``[ packed = false ]`` ，而在proto v3里是 ``[ packed = false ]`` 。
+简单地说，就是proto v2里数字类型的 ``repeated`` 字段默认是 ``[ packed = false ]`` 。打包结构是每个项目一个Key-Value数据对。
+而在proto v3里是 ``[ packed = false ]`` 。打包结构是Key-Value个数N，而后紧挨着N个Value。
 这可能导致转出的数据无法正常读取。解决方法也很简单，那就是对数字类型的 ``repeated`` 字段手动指定是否是packed。如：
 
 .. code-block:: proto
+
     message arr_in_arr {
         optional string name = 1;
         repeated int32 int_arr = 2 [ packed = true ];
@@ -230,6 +232,7 @@ Proto v2和Proto v3
 或proto v3版本。
 
 .. code-block:: proto
+
     message arr_in_arr {
         string name = 1;
         repeated int32 int_arr = 2 [ packed = true ];