Read the Docs 文档管理

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

1. 遇见

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

这是一种常见的文档管理方案 —— 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，如下图页面

当然，直接访问 html 文件不是很方便，所以借助 sphinx-autobuild 工具启动 HTTP 服务

$ sphinx-autobuild source build/html

在浏览器输入 http://127.0.0.1:8000，可以得到一样的效果

6. 换装

在 Sphinx Themes 可以找到 Sphinx 提供的可选主题

最熟悉是 sphinx_rtd_theme 主题，在前面已经安装了

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

重新进入页面查看，已同步更新了

7. 更新

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

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

修改 index.rst 文件，添加一个 text 页面

将会看到如下页面：

添加一个子目录
新建文件如下：

新增文件：

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/CSDNgithub/GitHubIndices and tables
==================* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

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

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/)

### 三级标题| 专业 | 职务 |
| :--: | :--: |
| 电动 | 厂仔 |#### 四级标题

或者可以使用在线工具转为rst文档：http://pandoc.org/try

9. 提交

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

build/

新建 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/ 注册，并绑定 GitHub 账户
点击 Import a Project 导入项目，输入项目名称和仓库地址即可

名称重复也是不允许的，需要调整一下名称，提交后等待一下

目前已成功了，点击 View your documentation，查阅

打完收工！中秋快乐！

谢谢

Read the Docs 文档管理相关推荐

ElasticSearch最全详细使用教程：入门、索引管理、映射详解、索引别名、分词器、文档管理、路由、搜索详解...
墨墨导读:之前我们分享了ElasticSearch最全详细使用教程:入门.索引管理.映射详解,本文详细介绍ElasticSearch的索引别名.分词器.文档管理.路由.搜索详解. 一.索引别名 1. ...
Linux内核的文档管理工具：Sphinx
Sphinx主页:https://www.sphinx-doc.org/en/master/index.html 使用Sphinx作为文档管理的主页: Linux内核:https://www.kern ...
云脉文档管理小程序轻松解决文档管理难题
手机h5访问地址:http://www.aipim.cn/docs 电脑端访问地址:http://www.yunmaiocr.com/goDoc 在日常处理办公文档过程中常常需要对纸质文档的文字内容进 ...
文档管理利器--云脉文档自动分类快速检索
大部分企业对文档的管理只是停留在简单的图片人工归类和查询,这样耗费了大量的人力.尤其是对于数据密集型的企业,急需通过优化所有文档驱动的业务流程来降低文档管理成本. 云脉文档管理基于超高识别率的OCR识 ...
egg+vue+mongodb实践开发在线文档管理平台——水墨文档
授权转载自:围的围 https://segmentfault.com/a/1190000037621367 前言团队中会遇到在线文档管理的需求,包括技术文档,接口文档, excel 文档,和产品原型 ...
自建低成本代码托管与文档管理平台经验分享
自建低成本代码托管与文档管理平台经验分享云服务器选择搭建Gitea服务仓库镜像管理树莓派备份节点 Nextcloud文件管理写在最后直入入正题,自建代码托管平台其实市面上早有成熟的方案,s ...
python api文档管理工具_开源的api文档管理系统
在项目中,需要协同开发,所以会写许多API文档给其他同事,以前都是写一个简单的TXT文本或Word文档,口口相传,这种方式比较老土了,所以,需要有个api管理系统专门来管理这些api,从网上找了许多比 ...
elasticsearch最全详细使用教程：入门、索引管理、映射详解、索引别名、分词器、文档管理、路由、搜索详解
一.快速入门 1. 查看集群的健康状况 http://localhost:9200/_cat http://localhost:9200/_cat/health?v 说明:v是用来要求在结果中返回表头 ...
elasticsearch系列三：索引详解（分词器、文档管理、路由详解（集群））
目录一.分词器 1. 认识分词器 1.1 Analyzer 分析器 1.2 如何测试分词器 2. 内建的字符过滤器(character filter) 2.1 HTML过滤字符过滤器(HTML S ...

Read the Docs 文档管理

Read the Docs 文档管理

1. 遇见

2. 浅谈

3. 搭建

4. 创建

5. 执行

6. 换装

7. 更新

8. 兼容

9. 提交

10. 托管

Read the Docs 文档管理相关推荐

最新文章

热门文章