1500字范文 > 【小沐学Python】Python实现电子书（Sphinx + readthedocs + github + Markdown）

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

时间：2018-08-14 15:20:23

文章目录

1、简介2、安装3、创建测试工程4、项目文件结构5、编译为本地文件6、编译为http服务7、更改样式主题8、支持markdown9、修改文档显示结构10、项目托管到github11、部署到ReadtheDocs结语

1、简介

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

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

2、安装

本文开发环境：

Windows系统

python3环境

安装Sphinx：

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

3、创建测试工程

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

mkdir SphinxDemocd SphinxDemosphinx-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 bysphinx-quickstart on Sun Jun 11 10:29:33 .You can adapt this file completely to your liking, but it should at leastcontain 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./simple sphinx-autobuild

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

sphinx-autobuild source build/html

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

7、更改样式主题

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

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

pip install -i https://pypi.tuna./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./simple recommonmark

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

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

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

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

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

9、修改文档显示结构

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

index.rst默认内容如下：

index.rst修改内容如下：

.. 小沐日记 documentation master file, created bysphinx-quickstart on Sun Jun 11 10:29:33 .You can adapt this file completely to your liking, but it should at leastcontain the root `toctree` directive.Welcome to 小沐日记's documentation!====================================.. toctree:::maxdepth: 3:caption: Contents:西游记/indexIndices 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.mdgit init# git add README.md# git add -Agit add .git commit -m "first commit"git branch -M maingit remote add origin /fxyublib/yxy_note.gitgit push -u origin main

命令执行过程如下：

github网站的内容更新如下：