[WINDOWS]最新Read the Docs配置详细步骤

安装

1. 安装python

2. 打开cmd，输入

   > pip install sphinx sphinx-autobuild
   

   这个时候等候安装，安装的东西有点多，而且使用国内网速下载超级慢，最好建议是挂个梯子下载， 速度就会快的飞起。！！！

3. 安装好了之后，依旧是在cmd窗口，这时候注意！！！如果你直接开始输入下面的代码，那么初始化好的文件会出现在 "C:\Users\user" 目录下，所以为了方便管理，我们需要把CMD所在的位置做出更改，选择方便自己管理的文件夹，例如我就是选择桌面的一个文件夹，然后建立名为 "docs" 的文件，紧接着初始化。

   > CD C:\Users\user\Desktop\文件名
   > md docs     #md是mkdir的缩写，两者等价
   > sphinx-quickstart
   

设置

接下来进入一个设置向导，根据向导一步步来设置文档项目。

有些后面有"[]"符号内容的是指默认选项，可以不填写内容直接回车！

• 是否分离文档源代码与生成后的文档

  You have two options for placing the build directory for Sphinx output.
  Either, you use a directory "_build" within the root path, or you separate
  "source" and "build" directories within the root path.

  你有两个选项可用于设置Sphinx输出的构建目录。

  你可以在根路径中使用目录"_build"[y] 或分成"source" 和 "build"两个目录[n]。

  > Separate source and  directories (y/n) [n]:     #默认为否
  

• 模板与静态文件存放目录前缀

  Inside the root directory, two more directories will be created;
  "_templates"for custom HTML templates and "_static" for custom stylesheets and other staticfiles.
  You can enter another prefix (such as ".") to replace the underscore.

  在根目录，将创建两个以上的目录；
  "_templates"为了自定义HTML模板
  "_static"为了自定义样式表和其他静态文件
  你可以输入其他的前缀（比如"."）来替换掉下划线。

  > Name prefix for templates and static dir [_]:    #默认为"_"
  

• 项目名称 & 作者名称 & 完整的项目版本

  The project name will occur in several places in the built documentation.

  将出现在内置文档的几个项目信息。

  > Project name:
  > Author name(s):      #默认命名为"s"
  > Project release []:
  

• 项目语言

  If the documents are to be written in a language other than English,
  you can select a language here by its language code. Sphinx will then
  translate text that it generates into that language.

  For a list of supported codes, see
  http://sphinx-doc.org/config.html#confval-language.

  意思是如果你使用英语以外的语言来写文本内容，你可以通过选择其他语言的代码来写，Sphinx会翻译成你想要的语言。

  有关支持代码的列表，看他下面的网址。

  > Project language [en]:     #默认"en"这里我们选择zh_CN
  

• 文档默认扩展名

  The file name suffix for source files. Commonly, this is either ".txt"
  or ".rst". Only files with this suffix are considered documents.

  源文件的文件名设置，是在".txt"或者".rst"二选一。

  > Source file suffix [.rst]:   #默认是".rst"格式，建议选择".txt"格式
  

• 主文档的名称（不带后缀）

  One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally,

  this is "index", but if your "index" document is a custom template,

  you can also set this to another filename.

  有一个文档是特殊的，他属于“内容树“的最顶端，也就是说他是层次结构的根源。

  换句话说，它被叫做”索引“，如果你的”索引”文件属于自定义模板，

  那么你也可以把它设置为其他文件名。

  > Name of your master document (without suffix) [index]:  #默认命名为index
  

• 增添epub输出配置

  Sphinx can also add configuration for epub output:

  Sphinx 也可以增加epub输出的配置

  > Do you want to use the epub builder (y/n) [n]:   #默认为否
  

• 选择Sphinx插件

  Indicate which of the following Sphinx extensions should be enabled:

  指出下列Sphinx哪些插件可以启用

  > autodoc: automatically insert docstrings from modules (y/n) [n]:
  > doctest: automatically test code snippets in doctest blocks (y/n) [n]:
  > intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
  > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
  > coverage: checks for documentation coverage (y/n) [n]:
  > imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
  > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
  > ifconfig: conditional inclusion of content based on config values (y/n) [n]:
  > viewcode: include links to the source code of documented Python objects (y/n) [n]:
  > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
  #autodoc:从模块中自动插入代码
  #doctest:在文档中自动测试代码段
  #intersphinx:在不同的项目文档中的链接
  #todo:写入“todo”条目，可以在构建文档中显示或隐藏
  #coverage:检查文档覆盖率
  #imgmath:提供PNG或SVG图像(包含数学)
  #mathjax:提供浏览器插件MathJax(包含数学)
  #ifconfig:根据配置值的内容纳入条件
  #viewcode:包含指向Python对象源代码的链接
  #githubpages:创建.nojekyll文件以在GitHub页面上发布文档
  

• 生成Makefile文件

  A Makefile and a Windows command file can be generated for you so that you
  only have to run e.g. `make html' instead of invoking sphinx-build
  directly.

  为你生成一个Makefile文件和Windows命令文件，这样你只需要运行"make html"而不是"sphinx-build"命令了。

  > Create Makefile? (y/n) [y]:  #默认选是
  > Create Windows command file? (y/n) [y]:  #默认选是
  

• 没了，配置结束啦~~

  Creating file .\source\conf.py.
  Creating file .\source\index.txt.
  Creating file .\Makefile.
  Creating file .\make.bat.
  
  Finished: An initial directory structure has been created.
  
  You should now populate your master file .\source\index.txt and create other documentation
  source files. Use the Makefile to build the docs, like so:
     make builder
  where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
  

  已完成，创建结构初始目录结构。

  你现在可以填充你的主文件".\source\index.txt"并创建其他文档源文件。

  使用Makefile来构建文档，例如：make builder

  其中"builder"是构建器之一，其他例如：html、latex或者linkcheck。

未完待续ing...