From 54f6fbb6649d4c2a5947c2ed1ade750b8485ff05 Mon Sep 17 00:00:00 2001
From: Tony031218 <975062472@qq.com>
Date: Thu, 18 Jun 2020 12:22:56 +0800
Subject: [PATCH] 20-06-18

update README

clean deploy.yml

finish setting up github action
---
 .github/workflows/deploy.yml | 22 ++++--------
 README.md                    | 66 +++++++++++++++++++++---------------
 2 files changed, 46 insertions(+), 42 deletions(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 2e8d3825..136809bb 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -2,7 +2,7 @@ name: Build up document
 
 on:
   push:
-    branches: [ master ]
+    branches: [ master, manim ]
 
 jobs:
   build_docs_and_deploy:
@@ -16,11 +16,11 @@ jobs:
     - name: Clone pre repositories
       run: |
         cd ..
-        git clone https://github.com/manim-kindergarten/manim.git
+        git clone -b manim https://github.com/manim-kindergarten/manim_document_zh.git manim
         cd manim
         git clone https://github.com/manim-kindergarten/manim_sandbox.git
     
-    - name: install setuptools
+    - name: Install setuptools
       run: |
         cd ..
         pip3 install --upgrade pip
@@ -29,11 +29,8 @@ jobs:
         cd setuptools-19.6
         sudo python3 setup.py build
         sudo python3 setup.py install
-        echo "finish installing setuptools"
-        pip3 list
-        export PATH="$PATH:/home/runner/.local/bin"
     
-    - name: install sphinx
+    - name: Install sphinx
       run: |
         cd ..
         git clone https://github.com/sphinx-doc/sphinx
@@ -42,25 +39,20 @@ jobs:
         pip3 install sphinx_rtd_theme
         pip3 install jieba
     
-    - name: install manim env
+    - name: Install manim env
       run: |
         cd ../manim
         pip3 install -r requirements.txt
-        cd ..
     
-    - name: build sphinx doc
+    - name: Build document with Sphinx
       run: |
         export PATH="$PATH:/home/runner/.local/bin:/home/runner/manim_document_zh/manim"
         export PYTHONPATH="$PYTHONPATH:/home/runner/manim_document_zh/manim"
-        sudo apt install tree -y
-        cd ../../
-        tree -L 4
-        cd manim_document_zh/manim_document_zh
         make html
         cd build/html
         echo "manim.ml" > CNAME
         
-    - name: Build up and deploy
+    - name: Deploy to GitHub pages
       uses: JamesIves/github-pages-deploy-action@master
       env:
         ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
diff --git a/README.md b/README.md
index 110ae5a3..82b04714 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,18 @@
 [![manim_document_zh](source/assets/image/DocumentHeader.png)](https://github.com/manim-kindergarten/manim_document_zh)
 
+![Build up document](https://github.com/manim-kindergarten/manim_document_zh/workflows/Build%20up%20document/badge.svg)
 [![GPL License](https://img.shields.io/github/license/manim-kindergarten/manim_document_zh)](https://choosealicense.com/licenses/gpl-3.0/)
 ![QQ](https://img.shields.io/badge/QQ-862671480-red.svg?style=flat)
 [![manim_sandbox](https://img.shields.io/badge/mk-manim__sandbox-brightgreen.svg)](https://github.com/manim-kindergarten/manim_sandbox/)
 [![manim](https://img.shields.io/badge/manim-ver.MK-orange.svg)](https://github.com/manim-kindergarten/manim)
 [![tutorial](https://img.shields.io/badge/tutorial-on_bilibili-ff69b4.svg)](https://space.bilibili.com/171431343/favlist?fid=947158443)
 
+[manim-kindergarten](https://github.com/manim-kindergarten/)成员整理的一份manim中文文档教程，目前还在完善当中。如果关于文档内容有问题，可以在这个repo中提出issue。
+如果你想要为这个文档做出贡献，可以提交pr。
 
-[manim-kindergarten](https://github.com/manim-kindergarten/)成员整理的一份manim中文文档教程
+[`manim`](https://github.com/manim-kindergarten/manim_document_zh/tree/manim)分支中为带有文档字符串的manim源码，用于文档中自动构建文档字符串。
 
-### 文档地址
+## 文档地址
 https://manim.ml/
 
 还在完善中，目前完成情况：
@@ -23,14 +26,43 @@ https://manim.ml/
 - [x] camera
 - [x] utils
 
-### 关于构建文档
+## 关于文档构建
+当前这个repo使用了[GitHub Actions](https://github.com/features/actions)自动构建文档。当向`master`或`manim`分支`push`后，会自动触发。
 
-python安装Sphinx之后`make html`，生成网页。
-`make pdf`则是生成pdf，配置文件是conf.py，可以修改主题。
+使用`Sphinx`构建文档，并部署在[GitHub Pages](https://manim.ml/)上
 
-html文档支持中文搜索，需要安装sphinx插件要安装```pip install jieba```
+### 手动构建文档
 
-不习惯reStructuredText语法的可以pandoc把markdown等文件转换rst，或者JupyterNoteBook把py等文件转换rst。
+**Step 1.** 安装环境：
+- 确保安装了[manim](https://github.com/3b1b/manim/)环境
+- `pip install sphinx`安装Sphinx
+- `pip install sphinx_rtd_theme`安装rtd样式
+- `pip install jieba`使支持中文搜索
+
+**Step 2.** 准备目录结构：
+```text
+.
+├── manim/
+│   ├── manimlib/
+│   ├── manim_sandbox/
+│   ├── ...
+│   └── manim.py
+└── manim_document_zh/
+    ├── source/
+    │   ├── ...
+    │   └── conf.py
+    ├── ...
+    ├── make.bat
+    └── Makefile 
+```
+
+**Step 3.** 构建文档：
+
+在`manim_document_zh`文件夹中执行`make html`构建文档
+
+**附.** 文件格式转换：
+
+sphinx要求使用rst格式(reStructuredText语法)，可以使用pandoc把markdown等文件转换rst，或者JupyterNoteBook把py等文件转换rst。
 
 ```bash
 pandoc readme.md --from markdown --to rst -s -o readme.rst
@@ -50,23 +82,3 @@ output = pypandoc.convert_file('somefile.md', 'rst').replace("\r", "")
 with open("outputfile.rst", "w", encoding="utf8") as f:
     f.write(output)
 ```
-
-### 关于目录结构
-
-由于很多地方根据[manim](https://github.com/3b1b/manim/)源码和[manim_sandbox](https://github.com/manim-kindergarten/manim_sandbox/)源码自动构建，推荐的目录结构如下：
-
-```text
-.
-├── manim/
-│   ├── manimlib/
-│   ├── manim_sandbox/
-│   ├── ...
-│   └── manim.py
-└── manim_document_zh/
-    ├── source/
-    │   ├── ...
-    │   └──conf.py
-    ├── ...
-    ├── make.bat
-    └── Makefile 
-```