本文是关于自己写文档（不局限于接口文档）时的一些记录，一条流程，即：文档源码托管在 github-> 文档编写用 vscode 编辑器 -> 采用 sphinx+rst 标记语言 -> 发布到 rtd。
目录
下面是每部分的概述。
1. GitHub
代码托管平台，龙头般的存在，此用于托管文档源码，官网是：https://github.com
1.1 新建仓库
选择.gitignore 并通过 README.md 初始化。
1.2 检出或克隆仓库
可以使用 svn 检出或 git 克隆仓库到本地，看个人喜好，墙裂推荐 git！
2. VSCode
Visual Studio Code，微软力作，真心好用，用过的人都知道，官网是：https://code.visualstudio.com
主要记录下我常用的插件和配置：
2.1 Chinese (Simplified) Language Pack for Visual Studio Code
额，不用说，简体中文语言包
2.2 Python
支持很多中编程语言，按需安装，Python 的话顺道也安装 Anaconda 插件吧。
2.3 Shell Launcher
用以配置启动多种终端的，比如 powershell、cmd、wsl bash、git bash 等。
多说一句，当时终端这个问题折腾太久了，我需要 python、git 等命令，可是又想用 wsl 里的，最后也没一个完美的办法，只得安装了 Git for Windows，它带了一个 git-bash 使得可以支持 windows 的程序，又能作为默认终端虽比不上 wsl 可也比 cmd 强太多。后来用这个插件，配合快捷键开启多种类型终端。
2.4 Windows opacity
vscode 透明度的插件
2.5 backgound-cover
vscode 背景图插件，可配合 2.4 中透明度插件食用。
2.6 Bracket Pair Colorizer
小括号、大括号、中括号等等颜色高亮、对称显示
2.7 Indent-Rainbow
缩进浅颜色显示。
2.8 REST Client
可以在 vscode 中发起 API 请求的插件。
2.9 reStructuredText
支持 rst 标记语言的插件。
2.10 Settings Sync
很实在的插件，把 vscode 的配置、插件等信息上传到 github gist，或读取信息更新 vscode，可以说实现了一处上传、多处同步的效果，避免了重复性配置 vscode！
2.12 remote ssl
这个扩展插件能让 vscode 在 wsl 中运行。
- 打开 windows 上的 vscode，安装 remote ssl 扩展
- 在 windows 上输入 wsl 命令调起 wsl 终端，在 wsl 环境里随便找个目录输入 code . 命令（注意有个点，而这个 code 命令就是 vscode 安装目录 /bin/code，如果安装 vscode 时将命令添加到 PATH 中，这个命令可以直接使用，否则请使用绝对路径。）
- 上述命令第一次使用会很快安装好所需组件，并在 vscode 通知区有提示信息，完成后，在底部栏左下角会有 wsl 的提示字样（可能要重启下 vscode）
- 以后打开 vscode 就会自动连接到 wsl 中，你的扩展需要重新安装下（算是可以从原有扩展中一键安装）
- 更多参考官方文档
配置：顶部 [菜单栏、LOGO、关闭按钮等] 所在的背景颜色及底部 [状态等] 所在背景颜色的配置，如下示例底部是白底透明、顶部是护眼的绿色：
{
"other": "...",
"workbench.colorCustomizations": {
"editor.selectionBackground": "#f00",
"[Quiet Light]": {
"statusBar.background": "#ffffff00",
"statusBar.foreground": "#616161",
"titleBar.activeBackground": "#19CAAD",
"titleBar.activeForeground": "#191919",
},
},
"other": "..."
}
其他的主题、图标等网上很多样例，不再累述，这里贴一个我的截图和配置吧
{
"workbench.startupEditor": "newUntitledFile",
"workbench.colorTheme": "Quiet Light",
"files.exclude": {
"**/__pycache__": true,
"**/.eggs": true,
"**/*.egg-info": true,
"**/*.pyc": true,
"**/*.pyo": true
},
"workbench.tree.indent": 12,
"git.enableCommitSigning": true,
"git.path": "git.exe",
"git.enabled": true,
"python.pythonPath": "python.exe",
"python.linting.flake8Enabled": true,
"python.analysis.logLevel": "Warning",
"python.globalModuleInstallation": true,
"python.linting.pep8Enabled": true,
"terminal.external.windowsExec": "C:\\Git\\git-bash.exe",
"terminal.integrated.shell.windows": "C:\\WINDOWS\\System32\\wsl.exe",
"explorer.confirmDelete": false,
"files.encoding": "utf8",
"files.eol": "\n",
"sync.gist": "Setting Sync要求的github token for gist",
"backgroundCover.enabled": true,
"backgroundCover.imagePath": "C:/VSCodeBgImg/3.png",
"backgroundCover.opacity": 0.5,
"shellLauncher.shells.windows": [
{
"shell": "C:\\Windows\\System32\\cmd.exe",
"label": "cmd"
},
{
"shell": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
"label": "PowerShell"
},
{
"shell": "C:\\Git\\bin\\bash.exe",
"label": "Git bash"
},
{
"shell": "C:\\Windows\\System32\\bash.exe",
"label": "WSL Bash"
}
],
"breadcrumbs.enabled": false,
"workbench.statusBar.feedback.visible": false,
"workbench.tips.enabled": false,
"extensions.closeExtensionDetailsOnViewChange": true,
"window.zoomLevel": 0,
"window.titleBarStyle": "custom",
"bracketPairColorizer.forceUniqueOpeningColor": true,
"editor.minimap.enabled": true,
"editor.tabSize": 4,
"editor.detectIndentation": false,
"editor.insertSpaces": true,
"editor.wordWrap": "on",
"winopacity.opacity": 245,
//设置用户选中代码段的颜色
"workbench.colorCustomizations": {
"editor.selectionBackground": "#f00",
"[Quiet Light]": {
"statusBar.background": "#ffffff00",
"statusBar.foreground": "#616161",
"titleBar.activeBackground": "#19CAAD",
"titleBar.activeForeground": "#191919",
},
},
"TortoiseSVN.tortoiseSVNProcExePath": "TortoiseProc.exe",
"TortoiseSVN.autoCloseUpdateDialog": true,
"workbench.activityBar.visible": false,
"window.menuBarVisibility": "default",
"[javascript]": {
"editor.defaultFormatter": "HookyQR.beautify"
},
"[html]": {
"editor.defaultFormatter": "HookyQR.beautify"
},
"[json]": {
"editor.defaultFormatter": "HookyQR.beautify"
},
"rest-client.timeoutinmilliseconds": 5000,
"workbench.iconTheme": "vscode-icons"
}
3. Sphinx+RST
之前写过一个制作接口文档的记录，https://blog.saintic.com/blog/263.html
不局限于接口文档，用 sphinx 写书也绰绰有余，基于 rst 并增加了许多功能，十分强大，官网是：http://www.sphinx-doc.org， 这里是一个中文翻译文档：https://zh-sphinx-doc.readthedocs.io
sphinx 有很多主题可选，之后要托管的 rtd 有一款主题挺好，sphinx_rtd_theme，文档是：https://sphinx-rtd-theme.readthedocs.io
此外，我在使用这款主题时，增加了一些自定义配置，关于配置的详细文档是：http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
3.1 自定义 css
通过 sphinx-quickstart 建立的文档项目配置文件是 conf.py，自定义配置需要在这个文件中更改。
新增一行，比如：html_css_files = ['css/my.css']，姑且放到 html_static_path 这行后面，这个意思是引入 css/my.css 文件，这个文件放在 html_static_path 定义的目录下，一般是在 “文档项目 /_static“ 下，新建 css 目录，创建 my.css，例如：
@charset "utf-8";
.wy-nav-content {
max-width: 100% !important;
}
.ethical-rtd.ethical-dark-theme {
display:none;
}
示例的 css 用以将 sphinx_rtd_theme 主题的内容页右侧栏最大化、关闭左侧栏 rtd 显示的广告。
3.2 自定义 js
类似于自定义 css，配置项是 html_js_files = ['js/my.js']，同样在 html_static_path 定义的目录下新建 js 目录和 my.js 文件，可以写你的 js 代码。
3.3 logo
配置项是 html_logo，比如我的是：html_logo = '_static/images/logo.png'，不晓得为什么还需要写_static，这个参数不是很了解，google 得知的示例。
3.4 favicon
配置项是 html_favicon，类似 html_logo，比如 html_favicon = '_static/images/favicon.png'
4. ReadTheDocs
同样可以参考之前的文章：https://blog.saintic.com/blog/263.html
额外提一点，关于自定义域名部分，文档是：https://docs.readthedocs.io/en/stable/custom_domains.html
定位到项目 - 管理 - 域，可以添加你的域名，然后 CNAME 解析到.readthedocs.io，勾选上使用 HTTPS 后，无需其他操作，便可以支持安全访问，极其方便！
END
以上是个人使用记录，刚开始写 RST 不熟悉是很痛苦的，熟练后便能感觉到好处。
文章中示例仓库是：https://github.com/saintic/docs
示例文档地址是：https://docs.saintic.com