# Wiki

**Repository Path**: mixlyplus/Wiki

## Basic Information

- **Project Name**: Wiki
- **Description**: Mixly Wiki
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 4
- **Created**: 2019-10-03
- **Last Updated**: 2023-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mixly Wiki 

## Mixly Wiki 编写准备

### 注册gitee账号
https://gitee.com

### 安装github同步软件github-desktop 
https://desktop.github.com/

### 安装好用的文本编辑器sublime
http://www.sublimetext.com/

### 克隆项目到本地
* 打开github-desktop 软件，依次点击：File-Clone a Repository-URL，在URL中输入https://gitee.com/mixlyplus/Wiki
* 设置项目本地存储地址

![](images/clone_repo.jpg)

## 编写项目
* 打开github-desktop 软件，依次点击Repository-open in sublime Text,用sublime打开该项目进行编辑。

![](images/sublime.jpg)

## 项目目录说明
```
|--doc
   |--build  /*生成目录*/
      |--doctrees
      |--gettext /*语言包字段目录*/
      |--html /*本地预览目录*/
        |--index.html /*本地预览页面*/
   |--source /*源文件目录*/
      |--_static /*静态html文件目录*/
      |--_templates /*自定义模板目录*/
      |--Arduino /*Arduino部分wiki目录*/
        |--AVR /*Arduino AVR 部分wiki*/
          |--images /*引用图片*/
            |--01Input-Output/*输入、输出类别图片*/
              |-- analogRead.png /*所有图片都用png格式，文件命名格式为该函数名*/
              |-- analogRead-example.png /*模块使用范例截图*/
              |-- analogRead.en.png /*analogRead.png对应的英文图片*/
              |-- analogRead-example.en.png /*analogRead-example.png对应的英文图片*/
            |--01Input-Output.rst /*输入\输出的wiki文件*/
        |--ESP32 /*ESP32 部分wiki*/
      |--basic /*软件基础部分wiki目录*/
      |--locale /*多语言目录*/
        |--en   /*英文语言翻译文件*/
      |--MicroPython /*micropython部分wiki目录*/
      |--Python /*python部分wiki目录*/

```
以 arduino/AVR为例进行目录说明，arduino/AVR目录中包含多个rst文件，rst为wiki的核心文件，通过编辑该类文件创建wiki。

在编写mixly wiki过程中可以参考 arduino语法。

编写wiki所使用rst文档采用的是Sphinx，常用语法可以参考下面链接。
https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html

## Arduino 语法参考
http://www.cnblogs.com/xczr/p/7832015.html

https://www.arduino.cc/reference/en/

## wiki编写说明

根据mixly模块顺序，介绍每一个模块。包括截图、描述、参数、返回值、范例、注释（注意点）。

编写文件可以参考```source\Arduino\AVR\01Input-Output.rst```

显示效果可以参考 https://mixly.readthedocs.io/zh_CN/latest/arduino/02.Input-Output.html

## 提交代码

修改文本后，按照下图操作提交代码。
![](images/commit.png)

## 本地预览
* 安装python3.x
* 打开cmd，输入以下命令，配置基础环境
```
pip install -U Sphinx
pip install sphinx_rtd_theme
pip install --upgrade recommonmark
```
* 跳转到本地项目路径，执行生成命令
```
cd Documents\GitHub\mixly_wiki\doc
make html
```
![](images/cmd.png)
* 打开build/html/index.html，查看本地预览。

## 在线预览
在提交代码之后，浏览https://mixly.readthedocs.io/zh_CN/latest/

## 翻译wiki

### 安装sphinx-intl.

```pip install sphinx-intl```

### 生成pot文件
运行以下命令生成pot文件
windows系统下,注意后面的命令都是在doc目录下进行的。
```
cd doc
make.bat gettext
```
或者直接
```
.\doc\make.bat gettext
```
如果提示
```
Extension error:
Could not import recommonmark.parser (needed for source parser) (exception: No module named 'recommonmark')
```
那么请运行
```pip install recommonmark```就可以了。
运行完成后会生成新目录 ：```doc/build/gettext```

### 生成英文翻译文件
```
sphinx-intl update -p build/gettext -l en
```
执行完成后，产生如下目录
```source/locale/en/LC_MESSAGES/```

### 翻译po文件
打开```source/locale/en/LC_MESSAGES/```目录下的po文件，进行翻译。

如原始：
```
#: ../../source/arduino/AVR/01Input-Output.rst:2
msgid "输入/输出"
msgstr ""
```
翻译后：
```
#: ../../source/arduino/AVR/01Input-Output.rst:2
msgid "输入/输出"
msgstr "Input/Output"
```
即，msgid为翻译前语言的内容，msgstr为翻译后语言的内容。

### 编译html文档

```
set SPHINXOPTS=-D language=en
.\make.bat html
```

### 查看最终效果

将文档提交到gitee，打开wiki页面，https://mixly.readthedocs.io

左下角打开功能框，切换到en，查看效果。

## 支持pdf导出(高级应用)

### Mac 配置环境

Sphinx 生成 PDF 的过程先将 rst 转换为 tex，再生产PDF。这个过程遇到了比较多的坑，最后总结下来过程如下：
首先，安装 Tex 环境。在 Mac 上，推荐安装 MacTex 而不是 BasicTex，对于新手来说 BasicTex 上需要自己处理很多以来问题。完成后使用 tlmgr 更新 TexLive。

$ brew cask install mactex
$ sudo tlmgr update --self

然后，在 conf.py 中设置 latex_engine 和 latex_elements 两个参数。
```
latex_engine = 'xelatex'
latex_elements = {
    'papersize': 'a4paper',
    'pointsize': '11pt',
    'preamble': r'''
\usepackage{xeCJK}
\setCJKmainfont[BoldFont=STZhongsong, ItalicFont=STKaiti]{STSong}
\setCJKsansfont[BoldFont=STHeiti]{STXihei}
\setCJKmonofont{STFangsong}
\XeTeXlinebreaklocale "zh"
\XeTeXlinebreakskip = 0pt plus 1pt
\parindent 2em
\definecolor{VerbatimColor}{rgb}{0.95,0.95,0.95}
\setcounter{tocdepth}{3}
\renewcommand\familydefault{\ttdefault}
\renewcommand\CJKfamilydefault{\CJKrmdefault}
'''
}
```
### 编译pdf

$ make latexpdf

make latexpdf 会完成 rst转换为 tex 并将 tex 生成 PDF，可以手动分开：
$ make latex
$ cd build/latex
$ make

在 build/latex 下可以查看到生成的 PDF 文档。

### 自动预览

安装库

`pip install sphinx-autobuild`

运行

`sphinx-autobuild source build/html`


## 贡献者