本文是关于自己写文档（不局限于接口文档）时的一些记录，一条流程，即：文档源码托管在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



·End·