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模板网!