Read the Docs 从懵逼到入门

《GitBook 从懵逼到入门》,时隔两年,终于推出姐妹篇《Read the Docs 从懵逼到入门》。从阅读量来看,笔者已经感受到大家对 GitBook 和 Markdown 写作的关注度,所以决定再给大家介绍一种常见的文档管理方案 —— Sphinx + GitHub + Read the Docs 的文档管理方法。

简单来说,就是先用 Sphinx 生成文档,然后用 GitHub 托管文档,再导入到 Read the Docs 生成在线文档。

无论是管理技术文档、写书、写笔记,亦或想搭建一个属于你的个人知识库,都是一个不错的选择。那我们现在开始吧!

在这里插入图片描述


1. 背景知识

1.1 ReadtheDocs

Read the Docs 是一个基于 Sphinx 的免费文档托管项目。该项目在 2010 年由 Eric Holscher、Bobby Grace 和 Charles Leifer 共同发起。2011年3月,Python 软件基金会曾给 Read the Docs 项目资助 840 美元,作为一年的服务器托管费用。此后,受到越来越多开源社区和开发者的关注,2017年11月,Linux Mint 宣布将所有文档转移到 Read the Docs,目前 Read the Docs 已经托管了超过 90000 份文档。

在这里插入图片描述

1.2 Sphinx

Sphinx 是一个基于 Python 的文档生成项目。最早只是用来生成 Python 的项目文档,使用 reStructuredText 格式。但随着 Sphinx 项目的逐渐完善,目前已发展成为一个大众可用的框架,很多非 Python 的项目也采用 Sphinx 作为文档写作工具,甚至完全可以用 Sphinx 来写书。

在这里插入图片描述

Sphinx 是 Python 社区编写和使用的文档构建工具,由 Georg Brandl 在 BSD 许可证下开发,它可以令人轻松的撰写出清晰且优美的文档。除了天然支持 Python 项目以外,Sphinx 对 C/C++ 项目也有很好的支持,并在不断增加对其它开发语言的支持,有需要的小伙伴可以持续关注。

Sphinx(斯芬克斯)一词源自希腊语 Sphiggein,在古埃及神话中被描述为长有翅膀的怪物,大家熟知的人面狮身像就是 Sphinx 的一种。

在这里插入图片描述

1.3 reStructuredText

reStructuredText 是一种轻量级标记语言。它是 Python Doc-SIG(Documentation Special Interest Group)的 Docutils 项目的一部分,旨在为 Python 创建一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation(pod)的工具。Docutils 可以从 Python 程序中提取注释和信息,并将它们格式化为各种形式的程序文档。

值得注意的是,reStructuredText 是一个单词,不是两个,也不是三个。可以简写为 RST、ReST 或 reST,作为一种用于文本数据的文件格式,通常采用 .rst 作为文件后缀。

在这里插入图片描述

前面提到,Sphinx 使用 reST 作为标记语言。实际上,reST 与 Markdown 非常相似,都是轻量级标记语言。由于设计初衷不同,reST 的语法更为复杂一些。

Markdown 的目标很简单,就是为了更简单地写 HTML,完成 text-to-HTML 的任务。而 reST 的目标是,建立一套标准文本结构化格式用以将文档转化为有用的数据格式(简单来说,就是要实现一套简单、直观、明确、原文本可阅读的,且可以转化为其他格式的文档标记语言)。显然,reST 的目标更大一些。

2. 环境搭建

这里以 Ubuntu 为例(其他 Linux 发行版、MacOS 或 Windows 也行),首先安装 Python3、Git、Make 等基础软件。

sudo apt install git
sudo apt install make
sudo apt install python3
sudo apt install python3-pip 

然后安装最新版本的 Sphinx 及依赖。

pip3 install -U Sphinx

为了完成本示例,还需要安装以下软件包。

pip3 install sphinx-autobuild
pip3 install sphinx_rtd_theme
pip3 install recommonmark
pip3 install sphinx_markdown_tables

安装完成后,系统会增加一些 sphinx- 开头的命令。

sphinx-apidoc    sphinx-autobuild    sphinx-autogen    sphinx-build    sphinx-quickstart

3. 快速开始

3.1 创建项目

我们以建立 diary 日记文档系统为例,先创建并进入 diary 文件夹(后续所有操作都在该文件夹内)。执行 sphinx-quickstart 构建项目框架,将会出现如下对话窗口。

欢迎使用 Sphinx 3.2.1 快速配置工具。

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> 独立的源文件和构建目录(y/n) [n]: 

首先,询问你是否要创建独立的源文件和构建目录。实际上对应两种目录结构,一种是在根路径下创建“_build”目录,另一种是在根路径下创建“source”和“build”两个独立的目录,前者用于存放文档资源,后者用于保存构建生成的各种文件。根据个人喜好选择即可,比如我更倾向于独立目录,因此输入 y

接着,需要输入项目名称、作者等信息。

The project name will occur in several places in the built documentation.
> 项目名称: diary
> 作者名称: Rudy
> 项目发行版本 []: v1

然后,可以设置项目的语言,我们这里选择简体中文。

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 项目语种 [en]: zh_CN

OK,项目创建完成!(两种目录结构分别如下)

在这里插入图片描述

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

此时我们在 diary 目录中执行 make html,就会在 build/html 目录生成 html 相关文件。

在这里插入图片描述

在浏览器中打开 index.html,将会看到如下页面。

在这里插入图片描述

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

sphinx-autobuild source build/html

默认启动 8000 端口,在浏览器输入 http://127.0.0.1:8000 。但是看到的页面跟上图一样,那换个主题吧!

3.2 修改主题

打开 conf.py 文件,找到 html_theme 字段,修改为“classic”主题。

#html_theme = 'alabaster'
html_theme = 'classic'

保存!可以看到网页变成这样了

在这里插入图片描述

Sphinx 为我们提供了好多可选的主题,在 Sphinx Themes 都可以找到。大家最熟悉的应该是“sphinx_rtd_theme”主题,其实我们前面已经安装好了。

html_theme = 'sphinx_rtd_theme'

那就用这个主题吧!

在这里插入图片描述

4. 最佳实践

4.1 index.rst 语法

受篇幅限制,本文无法详细介绍 reST 语法,具体可查看官方文档 RESTRUCTUREDTEXT 简介,这里主要分析 index.rst 的内容。

.. diary documentation master file, created by
   sphinx-quickstart on Sat Oct 10 22:31:33 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to diary's documentation!
=================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
  • 第1-4行由 .. + 空格开头,属于多行评论(类似于注释),不会显示到网页上。
  • 第6-7行是标题,reST 的标题需要被双下划线(或单下划线)包裹,并且符号的长度不能小于文本的长度。
  • 第9-11行是文档目录树结构的描述,.. toctree:: 声明了一个树状结构(toc 即 Table of Content),:maxdepth: 2 表示目录的级数(页面最多显示两级),:caption: Contents: 用于指定标题文本(可以暂时去掉)。
  • 第15-20行是索引标题以及该标题下的三个索引和搜索链接。

4.2 《我的日记》

我们进入 source 目录,修改 index.rst 文件,将标题改为“我的日记”,并添加一个 about 页面。

我的日记
=================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   about

因此我们需要在 source 目录下新建一个 about.rst 文件,并写下内容:

关于
========

这是我的公开日记

打开浏览器,输入 http://127.0.0.1:8000,将会看到如下页面。

在这里插入图片描述

在这里插入图片描述

接下来,我们为日记添加一级子目录。先在 source/index.rst 中添加路径信息。

我的日记
=================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   2020/index
   about

在 source 目录下新建一个名为“2020”的文件夹,在“2020”文件夹中再创建“春、夏、秋、冬”四个文件夹,并且在其中分别创建 contents.rst 文件。最后,别忘了还有要新建一个 index.rst 文件。这一步完成后,2020 目录结构如下:

2020
├── index.rst
├── 春
│   └── contents.rst
├── 冬
│   └── contents.rst
├── 秋
│   └── contents.rst
└── 夏
    └── contents.rst

在 2020/index.rst 文件中添加如下内容。

2020年
=================================

.. toctree::
   :maxdepth: 2

   春/contents
   夏/contents
   秋/contents
   冬/contents

以及四个 contents.rst 文件的内容:

  • 春/contents.rst

    春季
    ========
    
    春眠不觉晓,处处闻啼鸟。
    
  • 夏/contents.rst

    夏季
    ========
    
    夏早日初长,南风草木香。
    
  • 秋/contents.rst

    秋季
    ========
    
    秋风吹不尽,总是玉关情。
    
  • 冬/contents.rst

    冬季
    ========
    
    冬尽今宵促,年开明日长。
    

好啦!打开浏览器看一下吧~

在这里插入图片描述

在这里插入图片描述

好啦,日记就先写到这吧!喜欢的小伙伴可以在 https://github.com/luhuadong/diary 点赞+下载。

4.3 支持 Markdown

前面我们都是用 reST 语法来操作,但如果我们想用 Markdown 写,或者有大量 Markdown 文档需要迁移怎么办呢?

虽然 Sphinx 默认不支持 Markdown 语法,但可以通过 recommonmark 插件来支持。另外,如果需要支持 markdown 的表格语法,还需要安装 sphinx-markdown-tables 插件。这两个插件其实我们前面已经安装好了,现在只需要在 conf.py 配置文件中添加扩展支持即可。

extensions = [
    'recommonmark',
    'sphinx_markdown_tables'
]

我们以“秋”为例,将 rst 文件修改为 md 文件。

cdmv contents.rst contents.md

修改 contents.md 文件,增加一些 Markdown 语法内容:

# 秋季

秋风吹不尽,总是玉关情。

## 二级标题


### 三级标题


#### 四级标题


这是一个**段落**

| 作者 | 朝代 | 评分 |
| :--: | :--: | :--: |
| 李白 |  唐  | 100  |

噔噔!打开浏览器,完美~

在这里插入图片描述

5. 文档托管

5.1 上传 GitHub

首先在 GitHub 上创建一个 diary 仓库。

在这里插入图片描述

在本地 diary 目录中添加 README.md 和 .gitignore 文件,在 .gitignore 文件中写入下面一行。

build/

表示不跟踪 build 目录,因为我们后面将使用 Read the Docs 进行文档的构建和托管。

接着依次执行如下命令即可。

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:luhuadong/diary.git
git push -u origin main

5.2 网页托管

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

在这里插入图片描述

翻车啦,构建失败!(构建成功的话,可以通过 diary-demo.readthedocs.io 链接访问在线文档)

在这里插入图片描述

原因是 GitHub 从 2020年10月1日起,把主分支的名称从 master 修改为 main 了,但是 Read the Docs 的构建脚本还没兼容。。。(好吧,你们操作的时候应该修好了)


在这里插入图片描述


在这里插入图片描述

《了不起的Markdown》(博文视点出品)

©️2020 CSDN 皮肤主题: 编程工作室 设计师:CSDN官方博客 返回首页
实付 9.90元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值