[DOC] Update documents

docs/requirements.txt

@@ -2,4 +2,5 @@ sphinx
 sphinx_rtd_theme
 sphinx_toggleprompt
 sphinx-gallery>=0.6
-nbsphinx
+nbsphinx
+m2r2

docs/source/conf.py

@@ -46,7 +46,8 @@ def copy_tree(src, tar):
     'sphinx.ext.mathjax',
     'sphinx_toggleprompt',
     'nbsphinx',
-    'sphinx_gallery.load_style'
+    'sphinx_gallery.load_style',
+    'm2r2'
 ]
 
 # extension variables setting

docs/source/tutorial/zh/parse.rst

@@ -6,5 +6,50 @@
 * 文本语法结构解析
 * 公式语法结构解析
 
+其目的是：
+
+
+1、将选择题中的括号，填空题中的下划线用特殊标识替换掉，并将字符、公式用$$包裹起来，使item能通过$符号准确的按照类型切割开；
+
+2、判断当前item是否合法，并报出错误类型。
+
+具体处理内容包括：
+--------------------
+
+1.匹配公式之外的英文字母、数字，只对两个汉字之间的字母、数字做修正，其余匹配到的情况视为不合 latex 语法录入的公式
+
+2.匹配“（  ）”型括号（包含英文格式和中文格式），即括号内无内容或为空格的括号，将括号替换$\\SIFChoice$
+
+3.匹配下划线，替换连续的下划线或下划线中夹杂空格的情况，将其替换为$\\SIFBlank$
+
+4.匹配latex公式，主要检查latex公式的完整性和可解析性，对latex 中出现中文字符发出警告
+
+文本语法结构解析
+--------------------
+
+
+将文本中的字母、数字等进行提取，将其转换为标准格式。
+
+Examples：
+::
+
+ >>> text = '生产某种零件的A工厂25名工人的日加工零件数_   _'
+ >>> text_parser = Parser(text)
+ >>> text_parser.description_list()
+ >>> text_parser.text
+ >>> '生产某种零件的$A$工厂$25$名工人的日加工零件数$\\SIFBlank$'
+
+
 公式语法结构解析
 --------------------
+
+可以检查公式是否合法。
+
+Examples：
+::
+
+ >>> text = '支持公式如$\\frac{y}{x}$，$\\SIFBlank$，$\\FigureID{1}$，不支持公式如$\\frac{ \\dddot y}{x}$'
+ >>> text_parser = Parser(text)
+ >>> text_parser.description_list()
+ >>> text_parser.fomula_illegal_flag
+ >>> 1

docs/source/tutorial/zh/pretrain.rst

@@ -12,8 +12,42 @@
 训练模型
 ---------
 
+基本步骤：
+#########
+
+1.确定模型的类型，选择适合的Tokenizer（GensimWordTokenizer、 GensimSegTokenizer），使之令牌化；
+
+2.调用train_vector函数，即可得到所需的预训练模型。
+
+Examples：
+::
+        >>> tokenizer = GensimWordTokenizer(symbol="gmas", general=True)
+        >>> token_item = tokenizer("有公式$\\FormFigureID{wrong1?}$，如图$\\FigureID{088f15ea-xxx}$,\
+        ... 若$x,y$满足约束条件公式$\\FormFigureBase64{wrong2?}$,$\\SIFSep$，则$z=x+7 y$的最大值为$\\SIFBlank$")
+        >>> print(token_item.tokens[:10])
+        ['公式', '[FORMULA]', '如图', '[FIGURE]', 'x', ',', 'y', '约束条件', '公式', '[FORMULA]']
+
+        # 10 dimension with fasstext method
+        train_vector(sif_items, "../../../data/w2v/gensim_luna_stem_tf_", 10, method="d2v")
+
 装载模型
 --------
+将所得到的模型传入I2V模块即可装载模型
+
+Examples：
+::
+        >>> model_path = "../test_model/test_gensim_luna_stem_tf_d2v_256.bin"
+        >>> i2v = D2V("text","d2v",filepath=model_path, pretrained_t2v = False)
+
 
 公开模型一览
 ------------
+
+模型训练数据说明：
+#########
+
+* 当前【词向量w2v】【句向量d2v】模型所用的数据均为 【高中学段】 的题目
+* 测试数据：[`OpenLUNA.json<http://base.ustc.edu.cn/data/OpenLUNA/OpenLUNA.json>`_]
+
+当前提供以下模型，更多分学科、分题型模型正在训练中，敬请期待
+    "d2v_all_256"(全科)，"d2v_sci_256"(理科)，"d2v_eng_256"（文科），"d2v_lit_256"(英语)

docs/source/tutorial/zh/seg.rst

@@ -10,9 +10,40 @@
 语义成分分解
 ------------
 
+特别的，由于选择题是以字典的形式给出，故需要进行特殊处理，这里可以调用./Utils/data中的dict2str4sif函数，将选择题形式的item转换为字符格式，并将题干和选项、各选项之间分割开来。
+
+Examples：
+::
+
+ >>> item = {
+
+  ...   "stem": r"若复数$z=1+2 i+i^{3}$，则$|z|=$",
+
+  ...   "options": ['0', '1', r'$\sqrt{2}$', '2'],
+
+  ... }
+
+ >>> item
+
+  {'stem': '若复数$z=1+2 i+i^{3}$，则$|z|=$', 'options': ['0', '1', '$\\sqrt{2}$', '2']}
+
+ >>> dict2str4sif(item, key_as_tag=False)
+
+  '若复数$z=1+2 i+i^{3}$，则$|z|=$0$\\SIFSep$1$\\SIFSep$$\\sqrt{2}$$\\SIFSep$2'
+
+
 结构成分分解
 ------------
 
+对切片后的item中的各个元素进行分词，提供深度选项，可以按照需求选择所有地方切分或者在部分标签处切分（比如\SIFSep、\SIFTag处）；对标签添加的位置也可以进行选择，可以在头尾处添加或仅在头或尾处添加。
 
+具有两种模式，一种是linear模式，用于对文本进行处理（使用jieba库进行分词）；一种是ast模式，用于对公式进行解析。
 
+Examples：
+::
 
+>>> test_item = r"如图所示，则$\bigtriangleup ABC$的面积是$\SIFBlank$。$\FigureID{1}$"
+>>> seg(test_item)
+>>> ['如图所示，则', '\\bigtriangleup ABC', '的面积是', '\\SIFBlank', '。', \FigureID{1}]
+>>> seg(test_item, symbol="fgm")
+>>> ['如图所示，则', '[FORMULA]', '的面积是', '[MARK]', '。', '[FIGURE]']

docs/source/tutorial/zh/sif.rst

@@ -1,2 +1 @@
-标准项目格式
-===============
+.. mdinclude:: ../../../SIF4TI_CH.md

docs/source/tutorial/zh/tokenize.rst

@@ -5,19 +5,47 @@
 在EduNLP中我们将令牌化分为不同的粒度，为避免歧义，我们定义如下：
 
 * 词/字级别：分词
+
 * 句级别：分句
+
 * 资源级别：令牌化
 
 分词
 -------
+对切片后的item中的各个元素进行分词，提供深度选项，可以按照需求选择所有地方切分或者在部分标签处切分（比如\SIFSep、\SIFTag处）；对标签添加的位置也可以进行选择，可以在头尾处添加或仅在头或尾处添加。
+
+具有两种模式，一种是linear模式，用于对文本进行处理（使用jieba库进行分词）；一种是ast模式，用于对公式进行解析。
 
 分句
 -------
 
+将较长的文档切分成若干句子的过程称为“分句”。每个句子为一个“令牌”（token）（待实现）。
+
+
 令牌化
 -------
+即综合解析，将带公式的句子切分为若干标记的过程。每个标记为一个“令牌”（token）。
+我们提供了多种已经封装好的令牌化器供用户便捷调用，下面是一个示例:
+
+
+    Examples：
+    --------
+    >>> items = ["已知集合$A=\\left\\{x \\mid x^{2}-3 x-4<0\\right\\}, \\quad B=\\{-4,1,3,5\\}, \\quad$ 则 $A \\cap B=$"]
+    >>> tokenizer = TextTokenizer()
+    >>> tokens = tokenizer(items)
+    >>> next(tokens)  # doctest: +NORMALIZE_WHITESPACE
+    ['已知', '集合', 'A', '=', '\\left', '\\{', 'x', '\\mid', 'x', '^', '{', '2', '}', '-', '3', 'x', '-', '4', '<',
+    '0', '\\right', '\\}', ',', '\\quad', 'B', '=', '\\{', '-', '4', ',', '1', ',', '3', ',', '5', '\\}', ',',
+    '\\quad', 'A', '\\cap', 'B', '=']
+
+
+
+
+
+通过查看"./EduNLP/Tokenizer/tokenizer.py"及"./EduNLP/Pretrain/gensim_vec.py"可以查看更多令牌化器，下面是一个完整的令牌化器列表
 
-我们提供了多种已经封装好的令牌化器供用户便捷调用，下面是一个示例
+* TextTokenizer
 
+* GensimSegTokenizer
 
-通过 可以查看更多令牌化器，下面是一个完整的令牌化器列表
+* GensimWordTokenizer

docs/source/tutorial/zh/vectorization.rst

@@ -1,2 +1,90 @@
 向量化
-========
+=========
+
+此部分提供了简便的接口，可以直接将传入的items经过转化得到向量。当前提供了是否使用预训练模型的选项，可根据需要进行选择，如不使用预训练模型则可直接调用D2V函数，使用预训练模型则调用get_pretrained_i2v函数。
+
+
+总体流程
+---------
+
+1.对传入的item进行解析，得到SIF格式；
+
+
+2.对sif_item进行成分分解；
+
+
+3.对经过成分分解的item进行令牌化；
+
+
+4.使用已有或者使用提供的预训练模型，将令牌化后的item转换为向量。
+
+
+不使用预训练模型:直接调用D2V
+---------
+
+使用自己提供的任一预训练模型（给出模型存放路径即可）将给定的题目文本转成向量。
+
+
+* 优点：可以使用自己的模型，另可调整训练参数，灵活性强。
+
+
+处理的具体流程
+
+
+1.调用get_tokenizer函数，得到经过分词后的结果；
+
+
+2.调用T2V模块，根据需要选择是否使用预训练的t2v模型
+
+Examples：
+::
+  >>> model_path = "../test_model/test_gensim_luna_stem_tf_d2v_256.bin"
+  >>> i2v = D2V("text","d2v",filepath=model_path, pretrained_t2v = False)
+  >>> i2v(item)
+
+使用预训练模型：直接调用get_pretrained_i2v
+---------
+
+使用 EduNLP 项目组给定的预训练模型将给定的题目文本转成向量。
+
+
+* 优点：简单方便。
+
+
+* 缺点：只能使用项目中给定的模型，局限性较大。
+
+
+* 调用此函数即可获得相应的预训练模型，目前提供以下的预训练模型：d2v_all_256、d2v_sci_256、d2v_eng_256、d2v_lit_256
+
+模型选择与使用
+#########
+
+根据题目所属学科选择预训练模型：(表格问题待解决)
+
+
+
++--------------------+------------------------+
+|    预训练模型名称   |  模型训练数据的所属学科  |
++====================+========================+
+|    d2v_all_256     |        全学科          |
++--------------------+------------------------+
+|    d2v_sci_256     |         理科           |
++--------------------+------------------------+
+|    d2v_lit_256     |         文科           |
++--------------------+------------------------+
+|    d2v_eng_256     |         英语           |
++--------------------+------------------------+
+
+
+处理的具体流程：
+
+1.下载相应的预处理模型
+
+
+2.将所得到的模型传入D2V，使用D2V进行处理
+
+Examples：
+::
+  >>> i2v = get_pretrained_i2v("d2v_sci_256")
+  >>> i2v(item)
+