Read the Docs 文档管理

电玩女神 2022-09-11 15:19 256阅读 0赞

### Read the Docs 文档管理 ###

*  1. 遇见
 *  2. 浅谈
 *  3. 搭建
 *  4. 创建
 *  5. 执行
 *  6. 换装
 *  7. 更新
 *  8. 兼容
 *  9. 提交
 *  10. 托管

--------------------

# 1. 遇见 #

最近几年经常可以看到官方说明文档、wiki、个人博客和软件教程都是下图这种形式：

![https://readthedocs.org/][https_readthedocs.org]  
这是一种常见的文档管理方案 —— **Sphinx** \+ **GitHub** \+ **Read the Docs** 的文档管理方法。

*  用 Sphinx 生成 文档
 *  用 GitHub 托管 文档
 *  用 Read the Docs 生成 在线文档

--------------------

# 2. 浅谈 #

Sphinx 是一个基于 Python 的文档生成项目，使用 reStructuredText 格式  
reStructuredText 是一种轻量级标记语言，简写为ReST，与 Markdown 非常相似，通常采用 `.rst` 作为文件后缀

[Read the Docs][] 是一个基于 Sphinx 的免费文档托管项目

--------------------

# 3. 搭建 #

安装 Python3、Git、Make 等基础软件

$ sudo apt install git make python3 python3-pip

安装最新版本的 Sphinx 及依赖

$ pip3 install -U Sphinx

还需要安装以下常用软件包

$ pip3 install sphinx-autobuild sphinx_rtd_theme recommonmark sphinx_markdown_tables

--------------------

# 4. 创建 #

创建并进入 `readthedocs`**文件夹**  
执行 sphinx-quickstart 构建项目框架：

$ sphinx-quickstart
    欢迎使用 Sphinx 4.2.0 快速配置工具。
    
    请输入接下来各项设置的值（如果方括号中指定了默认值，直接按回车即可使用默认值）。
    
    已选择根路径：.
    
    有两种方式来设置 Sphinx 输出的创建目录：
    一是在根路径下创建“_build”目录，二是在根路径下创建“source”和“build”两个独立的目录。
    > 独立的源文件和构建目录（y/n） [n]:

看个人吧，这里就y了

接着，需要输入项目名称、作者和项目发行版本等信息

项目名称将会出现在文档的许多地方。
    > 项目名称: readthedocs
    > 作者名称: Jove
    > 项目发行版本 []: v1.0.0
    > 项目语种 [en]:zh_CN

目创建完成

*  build：生成的文件的输出目录
 *  source/\_static：静态文件目录，比如图片等
 *  source/\_templates：模板目录
 *  source/conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 时选中的那些值，可以自行定义其他的值
 *  source/index.rst：文档项目起始文件
 *  make.bat：Windows 用命令行
 *  Makefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出

--------------------

# 5. 执行 #

此时在 readthedocs 目录中执行 make html

$ make html

在 `build/html` 目录生成 html 相关文件  
在浏览器中打开其中的 `index.html`，如下图页面  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center]  
当然，直接访问 html 文件不是很方便，所以借助 `sphinx-autobuild` 工具启动 HTTP 服务

$ sphinx-autobuild source build/html

在浏览器输入 [`http://127.0.0.1:8000`][http_127.0.0.1_8000]，可以得到一样的效果

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 1]

--------------------

# 6. 换装 #

在 [Sphinx Themes][] 可以找到 Sphinx 提供的可选主题  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 2]  
最熟悉是 [sphinx\_rtd\_theme][sphinx_rtd_theme] 主题，在前面已经安装了

打开`source/conf.py` 文件，找到 `html_theme` 字段，修改为`sphinx_rtd_theme`主题

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 3]  
重新进入页面查看，已同步更新了

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 4]

--------------------

# 7. 更新 #

在 `source` 目录下新建一个 `text.rst` 文件，内容如下：

Text
    =======================================
    
    CSDN 氢键H-H

修改 `index.rst` 文件，添加一个 text 页面  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 5]  
将会看到如下页面：  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 6]  
添加一个子目录  
新建文件如下：  
![在这里插入图片描述][f0dd36fe3fa74a6eba18b372638dbb5c.png_pic_center]  
新增文件：

*  source/unit/index.rst
 *  source/unit/csdn/CSDN.rst
 *  source/unit/github/GitHub.rst

在 source/unit/index.rst 文件中添加如下内容：

Unit
    =======================================
    
    .. toctree::
       :maxdepth: 2
       :caption: Contents:
    
       csdn/CSDN
       github/GitHub
    
    
    
    Indices and tables
    ==================
    
    * :ref:`genindex`
    * :ref:`modindex`
    * :ref:`search`

最后在 source/index.rst 文件中添加 `unit/index` ，新增章节如下：

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_17_color_FFFFFF_t_70_g_se_x_16_pic_center]

--------------------

# 8. 兼容 #

reST 语法不太常用，格式内容挺多的，这边就不介绍了  
可以查看官网它们的源码格式去尝试

对于用惯 **Markdown**，也很友好，可以通过 `recommonmark` 插件来支持兼容  
如果需要支持 markdown 的表格语法，还需要安装 `sphinx-markdown-tables` 插件  
这两个插件在前面已经安装好了，现在只需要在 `conf.py` 配置文件中添加扩展支持即可

extensions = [
        'recommonmark',
        'sphinx_markdown_tables'
    ]

以“CSDN.rst ”为例，将 rst 文件修改为 `md` 文件，且内容改为markdown

# CSDN
    ***
    ## 二级标题
    
    [氢键H-H](https://joveh-h.blog.csdn.net/)
    
    ### 三级标题
    
    | 专业 | 职务 |
    | :--: | :--: |
    | 电动 | 厂仔 |
    
    #### 四级标题

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 7]  
或者可以使用在线工具转为rst文档：[http://pandoc.org/try][http_pandoc.org_try]

--------------------

# 9. 提交 #

初始化git，并通过`.gitignore` 把 `build` 文件夹的内容忽略

build/

新建 requirements.txt 文件，平时使用可参考文章 [《Python依赖文件requirements.txt的生成和安装》][Python_requirements.txt]  
现在添加必要的插件，编辑如下，

sphinx_rtd_theme>=1.0.0
    recommonmark>=0.7.1
    sphinx_markdown_tables>=0.0.15

在 GitHub 上创建一个 Read-the-Docs 仓库，按步骤提交工程

git init
    git add .
    git commit -m "first commit"
    git branch -M main
    git remote add origin https://github.com/JoveH-H/Read-the-Docs.git
    git push -u origin main

--------------------

# 10. 托管 #

在 Read the Docs 网站 [`https://readthedocs.org/`][Read the Docs] 注册，并绑定 GitHub 账户  
点击 `Import a Project` 导入项目，输入项目名称和仓库地址即可

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_15_color_FFFFFF_t_70_g_se_x_16_pic_center]  
名称重复也是不允许的，需要调整一下名称，提交后等待一下  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_14_color_FFFFFF_t_70_g_se_x_16_pic_center]  
目前已成功了，点击 **View your documentation**，查阅

![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_17_color_FFFFFF_t_70_g_se_x_16_pic_center 1]  
打完收工！中秋快乐！

--------------------

谢谢

[https_readthedocs.org]: /images/20220828/5a622f99d7034db6b7b9d92146116cf8.png
[Read the Docs]: https://readthedocs.org/
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center]: /images/20220828/808eb685222a4b16a453089d78cc9845.png
[http_127.0.0.1_8000]: http://127.0.0.1:8000
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 1]: /images/20220828/d5eaa54aad3f428883271ae838bbc982.png
[Sphinx Themes]: https://sphinx-themes.org/
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 2]: /images/20220828/c4b28528476641338dd90f3f32ab90ef.png
[sphinx_rtd_theme]: https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 3]: /images/20220828/956a263498c94f40bbd581dcc86eadfd.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 4]: /images/20220828/b18c576fc356464799e9b75843d65dae.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 5]: /images/20220828/b0f5ce0fdf7d4e419006d1a8c0601cde.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 6]: /images/20220828/72263b2af7234300a1502d44030e68dc.png
[f0dd36fe3fa74a6eba18b372638dbb5c.png_pic_center]: /images/20220828/654e9ae5fd53463cbe1b7886ebad0b29.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_17_color_FFFFFF_t_70_g_se_x_16_pic_center]: /images/20220828/1fbf367ca1af48ffba983f84c6f2c099.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_20_color_FFFFFF_t_70_g_se_x_16_pic_center 7]: /images/20220828/65c9a8644f8e44fd868f67cc74f54776.png
[http_pandoc.org_try]: http://pandoc.org/try
[Python_requirements.txt]: https://joveh-h.blog.csdn.net/article/details/107124112
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_15_color_FFFFFF_t_70_g_se_x_16_pic_center]: /images/20220828/d84f50daaca343fab022f5183e7d3d6c.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_14_color_FFFFFF_t_70_g_se_x_16_pic_center]: /images/20220828/04e6011809a74a4c85010d479a35dea7.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5rCi6ZSuSC1I_size_17_color_FFFFFF_t_70_g_se_x_16_pic_center 1]: /images/20220828/b758a2e64da8489281ea6001e0f9d5a9.png