add an article of tutorial-cross-region-copy

doc/source/conf.py

@@ -22,6 +22,7 @@
 import six
 import re
 import pypandoc
+from pathlib import Path
 
 sys.path.insert(0, os.path.abspath('../..'))
 
@@ -185,9 +186,29 @@
      'Miscellaneous'),
 ]
 
-if six.PY3:
-    open("README.rst", "w").write(pypandoc.convert('../../README.md', 'rst'))
-    open("README_CN.rst", "w").write(pypandoc.convert('../../README_CN.md', 'rst'))
-else:
-    open("README.rst", "w").write(pypandoc.convert('../../README.md', 'rst').encode('utf8'))
-    open("README_CN.rst", "w").write(pypandoc.convert('../../README_CN.md', 'rst').encode('utf8'))
+
+def convert_file(src_file, target_folder='.'):
+    file_name = os.path.basename(src_file)
+    new_file_name = os.path.splitext(file_name)[0] + '.rst'
+    new_file_path = os.path.sep.join([target_folder, new_file_name])
+
+    print("**** convert: " + src_file + " to " + new_file_path)
+    if six.PY3:
+        open(new_file_path, "w").write(pypandoc.convert(src_file, 'rst'))
+    else:
+        open(new_file_path, "w").write(pypandoc.convert(src_file, 'rst').encode('utf8'))
+
+convert_file('../../README.md')
+convert_file('../../README_CN.md')
+
+
+def convert_folder(folder_path, target_folder=None):
+    target_folder = target_folder or folder_path
+    pathlist = Path(folder_path).glob('**/*.md')
+    for path in pathlist:
+        path_in_str = str(path)
+        convert_file(path_in_str, target_folder)
+
+
+convert_folder('../tutorials', './tutorials')
+

doc/source/tutorials/tutorial_manage_cross_region_copy.rst

@@ -1,5 +1,84 @@
 跨域复制项目配置
-=============================
+================
 
+介绍
+----
 
-内容敬请期待
+日志服务是在域(Region)范围内以项目(Project)为边界进行操作的,
+典型场景下客户会在多个域部署同一套日志项目和日志库来接受日志和查询日志的服务.
+因此常常需要跨域复制多个项目的配置.
+使用日志服务的CLI可以比较容易的达到这点.
+
+哪些数据需要复制
+----------------
+
+通常一个日志服务的配置包含以下部分:
+
+-  多个日志库(logstore), 以及其下面的
+
+   -  索引配置
+   -  logtail配置
+
+日志库也包含以下配置, 但是一般多个区域内的配置会有所不同,
+一般不需要复制.
+
+-  机器组
+-  机器组和logtail配置的关联
+
+**注意:** CLI也支持机器组相关复制, 但需要额外参数打开.
+
+复制项目配置到其他域
+--------------------
+
+这里假设已经完成了CLI的\ `安装 <http://aliyun-log-cli.readthedocs.io/en/latest/README_CN.html#id1>`__.
+
+1. 配置多区域账户
+~~~~~~~~~~~~~~~~~
+
+首先CLI中配置多个区域账户, 以便后续操作, 这一步也是一次性的.
+如果之前已经做过, 这里可以跳过.
+
+这里配置2个域的账户, 一个杭州公有云, 一个北京公有云.
+
+.. code:: shell
+
+    > aliyun configure AKID****123 AKKEY****123 cn-hangzhou.log.aliyuncs.com
+    > aliyun configure AKID****123 AKKEY****123 cn-beijing.log.aliyuncs.com bj
+
+**注意:** 这里的最后一个参数, 用于表明这个账户的名字, 以便后续使用.
+不传入默认是\ ``main``, 也是默认使用的账户,
+这里使用杭州的账户作为默认账户.
+
+**参考:**
+
+-  关于秘钥的配置,
+   可以参考\ `配置 <https://help.aliyun.com/document_detail/29064.html?spm=5176.doc29063.2.5.6Jz1cJ>`__
+-  关于日志服务在各个域的Endpoint地址,
+   可以参考\ `入口服务 <https://help.aliyun.com/document_detail/29008.html?spm=5176.doc29064.2.4.0tdmB5>`__
+
+2. 复制项目组配置到目标域
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+假设我们需要将杭州公有云的项目组\ ``project1``\ 复制到北京公有云,
+这可以这样操作:
+
+.. code:: shell
+
+    > aliyun log copy_project --from_project="project1" --to_project="project1" --to_client=bj
+
+这里CLI就会使用默认账户\ ``main``\ 来读取源项目组\ ``project1``\ 的相关配置,
+并使用账户\ ``bj``\ 来构建一个新的项目组\ ``project1``.
+
+3. 同域项目组配置复制
+~~~~~~~~~~~~~~~~~~~~~
+
+某些特殊情况, 我们需要在同一个域内复制项目组并保留所有配置项.
+
+这里我们复制账户\ ``bj``\ 下的\ ``project1``\ 为\ ``project2``:
+
+.. code:: shell
+
+    > aliyun log copy_project --from_project="project1" --to_project="project2" --copy_machine_group=true --client-name=bj
+
+**提示:**
+传入\ ``copy_machine_group``\ 为\ ``true``\ 可以复制机器组的配置以及Logtail配置的管理信息.

doc/tutorials/tutorial_manage_cross_region_copy.md

@@ -0,0 +1,67 @@
+# 跨域复制项目配置
+
+## 介绍
+日志服务是在域(Region)范围内以项目(Project)为边界进行操作的, 典型场景下客户会在多个域部署同一套日志项目和日志库来接受日志和查询日志的服务.
+因此常常需要跨域复制多个项目的配置. 使用日志服务的CLI可以比较容易的达到这点.
+
+## 哪些数据需要复制
+
+通常一个日志服务的配置包含以下部分:
+
+- 多个日志库(logstore), 以及其下面的
+  - 索引配置
+  - logtail配置
+
+日志库也包含以下配置, 但是一般多个区域内的配置会有所不同, 一般不需要复制.
+
+  - 机器组
+  - 机器组和logtail配置的关联
+
+**注意:** CLI也支持机器组相关复制, 但需要额外参数打开.
+
+## 复制项目配置到其他域
+
+这里假设已经完成了CLI的[安装](http://aliyun-log-cli.readthedocs.io/en/latest/README_CN.html#id1).
+
+### 1. 配置多区域账户
+
+首先CLI中配置多个区域账户, 以便后续操作, 这一步也是一次性的. 如果之前已经做过, 这里可以跳过.
+
+这里配置2个域的账户, 一个杭州公有云, 一个北京公有云.
+
+```shell
+> aliyun configure AKID****123 AKKEY****123 cn-hangzhou.log.aliyuncs.com
+> aliyun configure AKID****123 AKKEY****123 cn-beijing.log.aliyuncs.com bj
+```
+
+**注意:** 这里的最后一个参数, 用于表明这个账户的名字, 以便后续使用. 不传入默认是`main`, 也是默认使用的账户, 这里使用杭州的账户作为默认账户.
+
+**参考:**
+
+- 关于秘钥的配置, 可以参考[配置](https://help.aliyun.com/document_detail/29064.html?spm=5176.doc29063.2.5.6Jz1cJ)
+- 关于日志服务在各个域的Endpoint地址, 可以参考[入口服务](https://help.aliyun.com/document_detail/29008.html?spm=5176.doc29064.2.4.0tdmB5)
+
+### 2. 复制项目组配置到目标域
+
+假设我们需要将杭州公有云的项目组`project1`复制到北京公有云, 这可以这样操作:
+
+```shell
+> aliyun log copy_project --from_project="project1" --to_project="project1" --to_client=bj
+```
+
+这里CLI就会使用默认账户`main`来读取源项目组`project1`的相关配置, 并使用账户`bj`来构建一个新的项目组`project1`. 
+
+### 3. 同域项目组配置复制
+
+某些特殊情况, 我们需要在同一个域内复制项目组并保留所有配置项. 
+
+这里我们复制账户`bj`下的`project1`为`project2`: 
+
+```shell
+> aliyun log copy_project --from_project="project1" --to_project="project2" --copy_machine_group=true --client-name=bj
+```
+
+
+**提示:** 传入`copy_machine_group`为`true`可以复制机器组的配置以及Logtail配置的管理信息. 
+
+

requirements-doc.txt

@@ -1,4 +1,5 @@
 sphinxcontrib-github_ribbon
 pypandoc
 six
-aliyun-log-python-sdk
+aliyun-log-python-sdk
+pathlib