ReadtheDocs从懵逼到⼊门
继，时隔两年，终于推出妹篇《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 项⽬资助 84
0 美元，作为⼀年的服务器托管费⽤。此后，受到越来越多开源社区和开发者的关注，2017年11⽉，Linux Mint 宣布将所有⽂档转移到 Read the Docs，⽬前 Read the Docs 已经托管了超过90000 份⽂档。
Read the Docs ⽹站：
1.2 Sphinx
Sphinx 是⼀个基于 Python 的⽂档⽣成项⽬。最早只是⽤来⽣成 Python 的项⽬⽂档，使⽤ reStructuredText 格式。但随着 Sphinx 项⽬的逐渐完善，⽬前已发展成为⼀个⼤众可⽤的框架，很多⾮ Python 的项⽬也采⽤ Sphinx 作为⽂档写作⼯具，甚⾄完全可以⽤ Sphinx 来写书。
Sphinx 是 Python 社区编写和使⽤的⽂档构建⼯具，由 Georg Brandl 在 BSD 许可证下开发，它可以令⼈轻松的撰写出清晰且优美的⽂档。除了天然⽀持 Python 项⽬以外，Sphinx 对 C/C++ 项⽬也有很好的⽀持，并在不断增加对其它开发语⾔的⽀持，有需要的⼩伙伴可以持续关注。
Sphinx ⽹站：
Sphinx 使⽤⼿册：
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 的⽬标更⼤⼀些。
reStructuredText ⽹站：
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
/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
3.2 修改主题
打开 conf.py ⽂件，到 html_theme 字段，修改为“classic”主题。
#html_theme = 'alabaster'
html_theme ='classic'
保存！可以看到⽹页变成这样了
Sphinx 为我们提供了好多可选的主题，在 都可以到。⼤家最熟悉的应该是“sphinx_rtd_theme”主题，其实我们前⾯已经安装好了。html_theme ='sphinx_rtd_theme'
那就⽤这个主题吧！
4. 最佳实践
4.1 index.rst 语法
受篇幅限制，本⽂⽆法详细介绍 reST 语法，具体可查看官⽅⽂档 ，这⾥主要分析 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 ⽂件，并写下内容：
关于
========
这是我的公开⽇记
接下来，我们为⽇记添加⼀级⼦⽬录。先在 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
python怎么读文件夹下的文件夹
├──秋
│└── 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
冬季
========
冬尽今宵促，年开明⽇长。
好啦！打开浏览器看⼀下吧～
4.3 ⽀持 Markdown

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。