[feature]: add pycharm vscode docker environment (#293)

* add pycharm and vscode document * add post transform to fix links * recover git lfs configs
alibaba · Oct 13, 2022 · f9cb358 · f9cb358
1 parent 009c01b
commit f9cb358
Show file tree

Hide file tree

Showing 25 changed files with 154 additions and 19 deletions.
diff --git a/docs/images/develop/pycharm_docker_1.png b/docs/images/develop/pycharm_docker_1.png
diff --git a/docs/images/develop/pycharm_docker_10.png b/docs/images/develop/pycharm_docker_10.png
diff --git a/docs/images/develop/pycharm_docker_11.png b/docs/images/develop/pycharm_docker_11.png
diff --git a/docs/images/develop/pycharm_docker_12.png b/docs/images/develop/pycharm_docker_12.png
diff --git a/docs/images/develop/pycharm_docker_13.png b/docs/images/develop/pycharm_docker_13.png
diff --git a/docs/images/develop/pycharm_docker_14.png b/docs/images/develop/pycharm_docker_14.png
diff --git a/docs/images/develop/pycharm_docker_15.png b/docs/images/develop/pycharm_docker_15.png
diff --git a/docs/images/develop/pycharm_docker_16.png b/docs/images/develop/pycharm_docker_16.png
diff --git a/docs/images/develop/pycharm_docker_17.png b/docs/images/develop/pycharm_docker_17.png
diff --git a/docs/images/develop/pycharm_docker_18.png b/docs/images/develop/pycharm_docker_18.png
diff --git a/docs/images/develop/pycharm_docker_2.png b/docs/images/develop/pycharm_docker_2.png
diff --git a/docs/images/develop/pycharm_docker_3.png b/docs/images/develop/pycharm_docker_3.png
diff --git a/docs/images/develop/pycharm_docker_4.png b/docs/images/develop/pycharm_docker_4.png
diff --git a/docs/images/develop/pycharm_docker_5.png b/docs/images/develop/pycharm_docker_5.png
diff --git a/docs/images/develop/pycharm_docker_6.png b/docs/images/develop/pycharm_docker_6.png
diff --git a/docs/images/develop/pycharm_docker_7.png b/docs/images/develop/pycharm_docker_7.png
diff --git a/docs/images/develop/pycharm_docker_8.png b/docs/images/develop/pycharm_docker_8.png
diff --git a/docs/images/develop/pycharm_docker_9.png b/docs/images/develop/pycharm_docker_9.png
diff --git a/docs/source/_ext/post_process.py b/docs/source/_ext/post_process.py
@@ -0,0 +1,38 @@
+import logging
+
+from docutils import nodes
+from docutils.transforms import Transform
+
+
+class PostFixLink(Transform):
+  default_priority = 780
+
+  def __init__(self, document, startnode=None):
+    super(PostFixLink, self).__init__(document, startnode)
+
+  def apply(self, **kwargs):
+
+    def _visit(node):
+      if not node.children:
+        return
+      for child in node.children:
+        if isinstance(child, nodes.Element):
+          if 'refuri' in child.attributes and '.md#' in child.attributes[
+              'refuri']:
+            src = child.attributes['refuri']
+            dst = src.replace('.md#', '.html#')
+            logging.info('[PostFixLink] replace %s to %s' % (src, dst))
+            child.attributes['refuri'] = dst
+        _visit(child)
+
+    _visit(self.document)
+
+
+def setup(app):
+  app.add_post_transform(PostFixLink)
+
+  return {
+      'version': '0.1',
+      'parallel_read_safe': True,
+      'parallel_write_safe': True,
+  }
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,15 +12,18 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
 
-import sphinx_markdown_tables  # NOQA
 import sphinx_rtd_theme
 
 import easy_rec
 
+# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('_ext'))
+
+import sphinx_markdown_tables  # NOQA
+
 # -- Project information -----------------------------------------------------
 
 project = 'easy_rec'
@@ -38,18 +41,11 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.napoleon',
-    'recommonmark',
-    'sphinx_markdown_tables',
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
+    'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages',
+    'sphinx.ext.napoleon', 'recommonmark', 'sphinx_markdown_tables',
+    'post_process'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -85,6 +85,7 @@ Welcome to easy_rec's documentation!
    :caption: DEVELOP
 
    develop
+   pycharm_vscode_docker
    release
 
 .. toctree::

diff --git a/docs/source/pycharm_vscode_docker.md b/docs/source/pycharm_vscode_docker.md
@@ -0,0 +1,101 @@
+# PyCharm / VSCode
+
+<style>
+img[alt=image_10.png] { height:320px; }
+img[alt=image_11.png] { height:320px; }
+</style>
+
+### 构建镜像
+
+```bash
+git clone https://github.com/Alibaba/EasyRec
+cd EasyRec
+sh scripts/build_docker.sh
+```
+
+### 运行容器
+
+- 查看docker镜像
+
+```bash
+docker images
+```
+
+![pycharm_docker_1.png](../images/develop/pycharm_docker_1.png)
+
+- 启动docker镜像
+
+```bash
+docker run -it <imageid> /bin/bash
+```
+
+### vscode配置
+
+#### 连接本地容器
+
+- vscode 安装 插件 remote - containers、remote - wsl 、remote development
+
+![pycharm_docker_2.png](../images/develop/pycharm_docker_2.png)
+
+- 安装插件后，vscode 状态栏会出现远程连接的图标，点击图标。remote_explorer 选择containers ，CONTAINERS 显示出 运行的容器。点击 + ，连接容器。
+
+![pycharm_docker_3.png](../images/develop/pycharm_docker_3.png)
+
+- 弹出新的window
+
+![pycharm_docker_4.png](../images/develop/pycharm_docker_4.png)
+
+#### 连接远程容器
+
+- vscode 安装 插件docker ，remote-ssh
+
+![pycharm_docker_5.png](../images/develop/pycharm_docker_5.png)
+![pycharm_docker_6.png](../images/develop/pycharm_docker_6.png)
+
+- vscode 连接远程服务器
+
+![pycharm_docker_7.png](../images/develop/pycharm_docker_7.png)
+
+- 弹出 window , 点击 docker 图标，展示出运行的容器
+
+![pycharm_docker_8.png](../images/develop/pycharm_docker_8.png)
+
+- 选择容器，右键attach shell，打开终端
+
+![pycharm_docker_9.png](../images/develop/pycharm_docker_9.png)
+
+### pycharm配置
+
+#### pycharm版本
+
+- 本示例使用的版本是: **professional 2022.2.2**
+
+#### 安装插件 docker
+
+![image_10.png](../images/develop/pycharm_docker_10.png)
+
+- 安装插件后 pycharm 底部的services会显示docker connect
+
+#### 配置docker 连接
+
+- 菜单路径: View=>Tools=>Services
+
+![image_12.png](../images/develop/pycharm_docker_12.png)
+
+- 本地docker: 选择 docker for mac
+- 远程服务器docker 选择 ssh, 填上 <username>@<ip>
+
+![image_15.png](../images/develop/pycharm_docker_15.png)
+
+- 确定后，显示出containers和images.
+
+![image_16.png](../images/develop/pycharm_docker_16.png)
+
+- 点击右上端terminal，进入交互.
+
+![image_17.png](../images/develop/pycharm_docker_17.png)
+
+- 选择容器，右键，点击show files ,显示容器内所有文件.
+- 选择文件，右键，查看和下载到本地.
+
+![image_18.png](../images/develop/pycharm_docker_18.png)
diff --git a/easy_rec/python/test/train_eval_test.py b/easy_rec/python/test/train_eval_test.py
@@ -7,11 +7,11 @@
 import threading
 import time
 import unittest
+from distutils.version import LooseVersion
 
 import numpy as np
 import six
 import tensorflow as tf
-from distutils.version import LooseVersion
 from tensorflow.python.platform import gfile
 
 from easy_rec.python.main import predict

diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh
@@ -14,5 +14,4 @@ pip install -r requirements/docs.txt
 cd docs
 rm -rf build
 make html
-find build/html/ -name "*.html" | xargs -I {}  sed -i -e "s/\/\([a-zA-Z0-9_%-]\+\)\.md#\([a-zA-Z0-9_%-]\)/\/\1.html#\2/g" {}
 rm -rf build/html/_modules
diff --git a/setup.cfg b/setup.cfg
@@ -10,7 +10,7 @@ multi_line_output = 7
 force_single_line = true
 known_standard_library = setuptools
 known_first_party = easy_rec
-known_third_party = absl,common_io,distutils,future,google,graphlearn,kafka,matplotlib,numpy,oss2,pai,pandas,psutil,six,sklearn,sphinx_markdown_tables,sphinx_rtd_theme,tensorflow,yaml
+known_third_party = absl,common_io,docutils,future,google,graphlearn,kafka,matplotlib,numpy,oss2,pai,pandas,psutil,six,sklearn,sphinx_markdown_tables,sphinx_rtd_theme,tensorflow,yaml
 no_lines_before = LOCALFOLDER
 default_section = THIRDPARTY
 skip = easy_rec/python/protos