使用Sphinx和Markdown自动创建和部署令人惊叹的文档（一）

创建有效的产品文档对于产品的成功和用户满意度至关重要。文档的结构、可读性和搜索性是显著影响客户体验的关键因素。在本文中，我将演示使用Sphinx工具和Markdown语言构建令人印象深刻的文档网站的简单性。同时使用Gitlab和Kubernetes (opens new window)部署。

介绍 #

Sphinx是一款使创建智能和美观文档变得简单的工具。Sphinx默认使用reStructuredText标记语言，并可以读取[My Markdown是一种常用的标记语言，可通过第三方扩展在Sphinx中使用。以下是安装和使用Markdown的步骤：

安装 #

Sphinx是一个Python包，您可以运行以下命令来安装它及相关包：

pip install sphinx sphinx-rtd-theme recommonmark sphinx-markdown-tables

sphinx — sphinx包
sphinx-rtd-theme — 著名的sphinx主题包
recommonmark — 用于支持Markdown的包
sphinx-markdown-tables — 用于支持Markdown表格的包

然后，使用类似以下命令初始化一个新项目：

sphinx-quickstart

回答问题以完成设置过程（记得选择将源代码和构建结果分开）。最后，初始化命令将生成一些文件夹和文件，包括：

source目录 — 所有内容（Markdown文件）存储在这里。
conf.py文件 — 存储了所有项目配置。
index.rst文件 — 主 make.bat文件—用于生成输出。

支持Markdown格式

为了支持Markdown格式，我们需要配置conf.py文件。打开它并添加或替换下面的行。完成后不要忘记保存。

source_suffix = {    ‘.rst’: ‘restructuredtext’,    ‘.md’: ‘markdown’}extensions = [   ‘recommonmark’,   ‘sphinx_markdown_tables’]html_theme = ‘sphinx_rtd_theme’

设置索引

Index.rst文件是我们之前提到的主要文档页面。它作为一个欢迎页面，包含了toc树（目录树）的根节点。根据您的需求修改它，以便拥有一个更漂亮的文档侧边栏部分。

.. toctree::   :maxdepth: 1   :hidden:   :caption: 第一部分:      docs/MyDoc1.md      docs/MyDoc1.md.. toctree::   :maxdepth: 2   :caption: 第二部分:      docs/MyDoc3.md      docs/MyDoc4.md      docs/MyDoc5.md

生成HTML

完成这个配置后，我们几乎完成了。运行以下命令以下是生成HTML输出的命令：

make html

该命令将生成HTML网站到 /build/html 目录下。
恭喜！您已经成功完成。
使用您喜欢的浏览器打开 /build/html/index.html 可以在本地查看您的文档。

到目前为止，我们已经使用Sphinx和Markdown创建了文档。接下来，我们将探讨如何利用Gitlab和Kubernetes自动部署它。