1、簡介
Sphinx 是一個 文檔生成器 ，您也可以把它看成一種工具，它可以將一組純文本源文件轉(zhuǎn)換成各種輸出格式，并且自動生成交叉引用、索引等。也就是說，如果您的目錄包含一堆 reStructuredText 或 Markdown 文檔，那么 Sphinx 就能生成一系列HTML文件，PDF文件（通過LaTeX），手冊頁等。
Sphinx 專注于文檔，尤其是 handwritten documentation ，然而，Sphinx 也可以用來生成博客、主頁甚至書籍。Sphinx 的大部分功能來自于 reStructuredText ，它是一種純文本標記格式，有著豐富的功能和 顯著的擴展能力 。
2、安裝
-
本文開發(fā)環(huán)境：
Windows系統(tǒng)
python3環(huán)境 -
安裝Sphinx：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx
3、創(chuàng)建測試工程
輸入如下命令初始化工程：
mkdir SphinxDemo
cd SphinxDemo
sphinx-quickstart
然后會有如下的輸出，需要根據(jù)提示輸入項目名稱、作者、版本號、語言等信息。
4、項目文件結(jié)構(gòu)
項目創(chuàng)建完成后，可以看到如下的目錄結(jié)構(gòu)：
|-- build <-------- 生成文件的輸出目錄
|-- make.bat <-------- Windows 命令行中編譯用的腳本
|-- Makefile <-------- 編譯腳本，make 命令編譯時用
`-- source <-------- 文檔源文件
|-- conf.py <-------- 進行 Sphinx 的配置，如主題配置等
|-- index.rst <-------- 文檔項目起始文件，用于配置文檔的顯示結(jié)構(gòu)
|-- _static <-------- 靜態(tài)文件目錄, 比如圖片等
`-- _templates <-------- 模板目錄
這里先簡單說明一下各個文件的作用：
- build：生成的文件的輸出目錄
- source: 存放文檔源文件
- _static：靜態(tài)文件目錄，比如圖片等
- _templates：模板目錄
- conf.py：進行 Sphinx 的配置，如主題配置等
- index.rst：文檔項目起始文件，用于配置文檔的顯示結(jié)構(gòu)
- cmd.bat：這是自己加的腳本文件（里面的內(nèi)容是‘cmd.exe’）,用于快捷的打開windows的命令行
- make.bat：Windows 命令行中編譯用的腳本
- Makefile：編譯腳本，make 命令編譯時用
其中index.rst內(nèi)容默認如下：
.. 小沐日記 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、編譯為本地文件
執(zhí)行如下命令：
make html
居然報錯，有沒有天理呢。哈哈。
換一種寫法如下：
./make html
自動生成如下這些文件：
可以在瀏覽器中預(yù)覽一下：
file:///C:/Users/tomcat/Desktop/SphinxDemo/build/html/index.html
6、編譯為http服務(wù)
上面使用make html的方式編譯，編譯完后需要打開html文件來查。
還有一種HTTP服務(wù)的方式，可以在瀏覽器器中通過ip地址來查看，該方式需要安裝自動build工具：
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx-autobuild
然后使用如下編譯指令進行編譯：
sphinx-autobuild source build/html
然后可以到瀏覽器中，輸入127.0.0.1:8000，進行預(yù)覽如下：
7、更改樣式主題
上面的測試效果，使用的是默認的主題alabaster，如果想安裝其它的主題，可以先到Sphinx的官網(wǎng)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'
再次編譯，預(yù)覽如下：
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、修改文檔顯示結(jié)構(gòu)
修改文檔結(jié)構(gòu)，需要修改index.rst文件。
index.rst默認內(nèi)容如下：
.. 小沐日記 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修改內(nèi)容如下：
.. 小沐日記 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”內(nèi)容如下：
西游記
=================================
.. toctree::
:maxdepth: 1
第一回、靈根育孕源流出 心性修持大道生/index
第二回、悟徹菩提真妙理 斷魔歸本合元神/index
第三回、四海千山皆拱伏 九幽十類盡除名/index
- 其中“source\西游記\第一回、靈根育孕源流出 心性修持大道生\index.rst”內(nèi)容如下：
第一回、靈根育孕源流出 心性修持大道生
=======================================
其他幾個類似如上。再次編譯，預(yù)覽如下：
sphinx-autobuild source build/html
- 第一級頁面：
- 第二級頁面：
- 第三級頁面：
10、項目托管到github
首先在github上創(chuàng)建倉庫，比如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
命令執(zhí)行過程如下：
github網(wǎng)站的內(nèi)容更新如下：
11、部署到ReadtheDocs
ReadtheDocs平臺(https://readthedocs.org/)
打開頁面：https://readthedocs.org/dashboard/
選擇手動導入一個項目：
設(shè)置項目的基本信息如下：
然后點擊按鈕“Build version”編譯代碼生成文檔網(wǎng)頁。
居然構(gòu)建失敗了。
原因是ReadTheDocs的python環(huán)境沒有對應(yīng)的第三方庫文件，需要在項目根目錄執(zhí)行如下命令生成requirements.txt，這樣ReadTheDocs會自動安裝對應(yīng)的插件依賴。
命令行執(zhí)行如下命令：
python3 -m pip freeze > requirements.txt
- requirements.txt：
sphinx-markdown-tables
再次編譯如下：
預(yù)覽生成的文檔如下：
文章來源：http://www.zghlxwxcb.cn/news/detail-643746.html
結(jié)語
如果您覺得該方法或代碼有一點點用處，可以給作者點個贊，或打賞杯咖啡；╮(￣▽￣)╭如果您感覺方法或代碼不咋地//(ㄒoㄒ)//，就在評論處留言，作者繼續(xù)改進；o_O???如果您需要相關(guān)功能的代碼定制化開發(fā)，可以留言私信作者；(????)感謝各位大佬童鞋們的支持！( ′ ▽′ )? ( ′ ▽′)っ?。?！文章來源地址http://www.zghlxwxcb.cn/news/detail-643746.html
到了這里，關(guān)于【小沐學Python】Python實現(xiàn)在線電子書制作（Sphinx + readthedocs + github + Markdown）的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
