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
再次编译如下：
预览生成的文档如下：
文章来源：https://www.toymoban.com/news/detail-643746.html
结语
如果您觉得该方法或代码有一点点用处，可以给作者点个赞，或打赏杯咖啡；╮(￣▽￣)╭如果您感觉方法或代码不咋地//(ㄒoㄒ)//，就在评论处留言，作者继续改进；o_O???如果您需要相关功能的代码定制化开发，可以留言私信作者；(✿◡‿◡)感谢各位大佬童鞋们的支持！( ´ ▽´ )ﾉ ( ´ ▽´)っ！！！文章来源地址https://www.toymoban.com/news/detail-643746.html
到了这里，关于【小沐学Python】Python实现在线电子书制作（Sphinx + readthedocs + github + Markdown）的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
