Windows下搭建readthedoc

1、安装python

• 下载链接

• 安装时注意勾选 加入PATH，打开Windows自带的PowerShell，如下有应答就算成功
  
• 输入指令安装如下软件包，等待安装完成

pip install  Sphinx
pip install  sphinx-autobuild
pip install  sphinx_rtd_theme

2、安装MinGW （make）

• 下载地址

• 解压后，复制存放的路径，在WIN10左下搜索栏查找环境变量，按照下图所示，最终把路径贴在Path内就行。示例中我复制进去的地址是D:\develop_tools\mingw\mingw64\bin
  

• 把解压文件内的mingw32-make.exe修改为make.exe，在powershell内输入指令make -v 查看是否成功
  
  

  3、生成文档模板

• 创建个文件夹，我这里示例是 D:\work_space\test，在powershell 内进入该文件内
  

• 输入指令 sphinx-quickstart 生成模板，我选择的是中文 zh_CN
  

• 输入指令 make html ，编译成功如下
  

• 找到文件夹build/html下的index.html，双击打开就行(浏览器)，就能看到生成的裸奔文档页面了
  

4、更换主题

• 在soure文件夹内找到conf.py，用记事本或其他工具打开，将html_theme内容修改为sphinx_rtd_theme
  
  
• 在powershell内输入指令make html 编译，查看最终输出的html文件，可以看到主题样式已变更
  

  5、增加子页面

• 新建两个.rst文件，如下所示，填入简单内容
  

• 修改index.rst内容，注意：page1左边必须是三个空格。移除Indices and tables
  

• 在powershell内输入指令make html 编译，查看最终输出的html文件，可以看到子页面已加入
  

  6、常规语法效果

• 在子页面1内加入一些内容如下：

子页面1
================================

子页面内容1



语法测试 (二级标题)
--------------------

``标红``

:guilabel:`蓝框`

**加粗**

.. tip::
   小技巧
   
.. note::
   备注

:doc:`导航到子页面2 </page2>`

.. code:: c

      static void hello(uint8_t in, uint32_t *p);
	  
+------+---------------------------------+
| 序号 | 表头                            |
+======+=================================+
| 1    | 第一行                          |
+------+---------------------------------+
| 2    | 第二行                          |
+------+---------------------------------+
| 3    | 第三行                          |
+------+---------------------------------+

• 在powershell内输入指令make html 编译，查看最终输出的html文件，可以看到语法效果如下
  

  7、托管文档

  • Read The Doc

  注册Github账号与ReadTheDoc账号，将本地readthedoc 的source文件等上传到Github，并通过ReadTheDoc官网导入项目，就可以将项目文档发布到公网上