【小沐学Python】Python实现在线电子书（Sphinx + readthedocs + github + Markdown）

1、简介

Sphinx 是一个 文档生成器 ，您也可以把它看成一种工具，它可以将一组纯文本源文件转换成各种输出格式，并且自动生成交叉引用、索引等。也就是说，如果您的目录包含一堆 reStructuredText 或 Markdown 文档，那么 Sphinx 就能生成一系列HTML文件，PDF文件（通过LaTeX），手册页等。

Sphinx 专注于文档，尤其是 handwritten documentation ，然而，Sphinx 也可以用来生成博客、主页甚至书籍。Sphinx 的大部分功能来自于 reStructuredText ，它是一种纯文本标记格式，有着丰富的功能和 显著的扩展能力 。

2、安装

• 本文开发环境：
  Windows系统
  python3环境

• 安装Sphinx：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx

3、创建测试工程

输入如下命令初始化工程：

mkdir SphinxDemo
cd SphinxDemo
sphinx-quickstart

然后会有如下的输出，需要根据提示输入项目名称、作者、版本号、语言等信息。

4、项目文件结构

项目创建完成后，可以看到如下的目录结构：

|-- build       <--------  生成文件的输出目录
|-- make.bat    <--------  Windows 命令行中编译用的脚本
|-- Makefile    <--------  编译脚本，make 命令编译时用
`-- source      <--------  文档源文件
    |-- conf.py     <--------  进行 Sphinx 的配置，如主题配置等
    |-- index.rst   <--------  文档项目起始文件，用于配置文档的显示结构
    |-- _static     <--------  静态文件目录, 比如图片等
    `-- _templates  <--------  模板目录

这里先简单说明一下各个文件的作用：

• build：生成的文件的输出目录
• source: 存放文档源文件
• _static：静态文件目录，比如图片等
• _templates：模板目录
• conf.py：进行 Sphinx 的配置，如主题配置等
• index.rst：文档项目起始文件，用于配置文档的显示结构
• cmd.bat：这是自己加的脚本文件（里面的内容是‘cmd.exe’）,用于快捷的打开windows的命令行
• make.bat：Windows 命令行中编译用的脚本
• Makefile：编译脚本，make 命令编译时用

其中index.rst内容默认如下：

.. 小沐日记 documentation master file, created by
   sphinx-quickstart on Sun Jun 11 10:29:33 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to 小沐日记's documentation!
====================================

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

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

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

5、编译为本地文件

执行如下命令：

make html

居然报错，有没有天理呢。哈哈。
换一种写法如下：

./make html

自动生成如下这些文件：

可以在浏览器中预览一下：

file:///C:/Users/tomcat/Desktop/SphinxDemo/build/html/index.html

6、编译为http服务

上面使用make html的方式编译，编译完后需要打开html文件来查。
还有一种HTTP服务的方式，可以在浏览器器中通过ip地址来查看，该方式需要安装自动build工具：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild

然后使用如下编译指令进行编译：

sphinx-autobuild source build/html

然后可以到浏览器中，输入127.0.0.1:8000，进行预览如下：

7、更改样式主题

上面的测试效果，使用的是默认的主题alabaster，如果想安装其它的主题，可以先到Sphinx的官网https://sphinx-themes.org/查看:

这里选用一个较为常用的主题Read the Docs，安装这个主题首先需要在python中进行安装，命令如下：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx_rtd_theme

然后修改conf.py 文件，找到 html_theme 字段，修改为

#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'

再次编译，预览如下：

sphinx-autobuild source build/html

8、支持markdown

这里安装markdown支持工具。Sphinx默认只支持reST格式的文件。
如果相要使用markdown格式的文档，还要安装markdown支持工具，命令如下：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple recommonmark

若要使用markdown的表格，还要安装：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx_markdown_tables

然后，还要修改conf.py 文件，找到 extensions字段，修改为:

#extensions = []
extensions = ['recommonmark','sphinx_markdown_tables']

支持markdown后，文档文件可以使用markdown格式，但文档的配置文件index.rst还要使用reST格式

9、修改文档显示结构

修改文档结构，需要修改index.rst文件。

index.rst默认内容如下：

.. 小沐日记 documentation master file, created by
   sphinx-quickstart on Sun Jun 11 10:29:33 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to 小沐日记's documentation!
====================================

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

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

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

index.rst修改内容如下：

.. 小沐日记 documentation master file, created by
   sphinx-quickstart on Sun Jun 11 10:29:33 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to 小沐日记's documentation!
====================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   西游记/index

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

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

• 其中“source\西游记\index.rst”内容如下：

西游记
=================================
 
.. toctree::
   :maxdepth: 1
   
   第一回、灵根育孕源流出　心性修持大道生/index
   第二回、悟彻菩提真妙理　断魔归本合元神/index
   第三回、四海千山皆拱伏　九幽十类尽除名/index

• 其中“source\西游记\第一回、灵根育孕源流出　心性修持大道生\index.rst”内容如下：

第一回、灵根育孕源流出　心性修持大道生
=======================================

其他几个类似如上。再次编译，预览如下：

sphinx-autobuild source build/html

• 第一级页面：
  
• 第二级页面：
  
• 第三级页面：
  

10、项目托管到github

首先在github上创建仓库，比如yxy_note，然后建立本地仓库：

echo "# yxy_note" >> README.md
git init
# git add README.md
# git add -A
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/fxyublib/yxy_note.git
git push -u origin main

命令执行过程如下：

github网站的内容更新如下：

11、部署到ReadtheDocs

ReadtheDocs平台(https://readthedocs.org/)
打开页面：https://readthedocs.org/dashboard/

选择手动导入一个项目：

设置项目的基本信息如下：

然后点击按钮“Build version”编译代码生成文档网页。

居然构建失败了。

原因是ReadTheDocs的python环境没有对应的第三方库文件，需要在项目根目录执行如下命令生成requirements.txt，这样ReadTheDocs会自动安装对应的插件依赖。
命令行执行如下命令：

python3 -m pip freeze > requirements.txt

• requirements.txt：

sphinx-markdown-tables

再次编译如下：

预览生成的文档如下：

结语

如果您觉得该方法或代码有一点点用处，可以给作者点个赞，或打赏杯咖啡；╮(￣▽￣)╭
如果您感觉方法或代码不咋地//(ㄒoㄒ)//，就在评论处留言，作者继续改进；o_O???
如果您需要相关功能的代码定制化开发，可以留言私信作者；(✿◡‿◡)
感谢各位大佬童鞋们的支持！( ´ ▽´ )ﾉ ( ´ ▽´)っ！！！