Sphinx+gitee+Read the Docs搭建在線文檔系統

本文介紹一種在線文檔系統的搭建，需要借助Sphinx、gitee和Read the Docs。

Sphinx是一個功能強大的文檔生成器，具有許多用于編寫技術文檔的強大功能

gitee是一種版本管理系統，相比github，有著更快的訪問速度

Read the Docs是一個在線文檔托管服務， 你可以從各種版本控制系統中導入文檔

1 安裝環境

Windows系統

python3環境

2 Sphinx安裝與測試

2.1 基礎功能安裝

首先是安裝Sphinx，在windows的命令行中輸入下面的命令

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

2.2 創建測試Demo

新建一個文件夾用來測試，比如SphinxDemo，進入該文件夾，命令行中執行下面的命令，新建一個Sphinx的項目框架。

sphinx-quickstart

2.3 項目文件結構

項目創建完成后，可以看到如下的目錄結構：

進入source文件夾，可以看到如下結構：

這里先簡單說明一下各個文件的作用：

build：生成的文件的輸出目錄

source: 存放文檔源文件

_static：靜態文件目錄，比如圖片等

_templates：模板目錄

conf.py：進行 Sphinx 的配置，如主題配置等

index.rst：文檔項目起始文件，用于配置文檔的顯示結構

cmd.bat：這是自己加的腳本文件（里面的內容是‘cmd.exe’）,用于快捷的打開windows的命令行

make.bat：Windows 命令行中編譯用的腳本

Makefile：編譯腳本，make 命令編譯時用

2.4 普通編譯

執行如下指令

make html

會輸出如下編譯結果：

G:\TestProject\sphinx\SphinxDemo>make html Running Sphinx v4.0.2 loading translations [zh_CN]... done making output directory... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex done writing additional pages... search done copying static files... done copying extra files... done dumping search index in Chinese (code: zh)... done dumping object inventory... done build succeeded. The HTML pages are in build\html. G:\TestProject\sphinx\SphinxDemo>

然后到build/html文件夾下，瀏覽器打開index.html文件 可以在瀏覽器中看到測試效果：

2.5 安裝autobuild工具

上面使用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查看效果：

2.6 更改樣式主題

上面的測試效果，使用的是默認的主題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'

再次編譯，查看效果：

3 修改測試程序

Sphinx默認只支持reST格式的文件，reST的使用語法介紹見：https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html

3.1 安裝markdown支持工具

如果相要使用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格式

3.2 修改文檔顯示結構

3.2.1 index文件分析

修改文檔結構，需要修改index.rst文件，首先來看一下這個文件中的內容：

.. SphinxDemo documentation master file, created by sphinx-quickstart on Sat Jun 26 17:56:51 2021. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to SphinxDemo's documentation! ====================================== .. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`

兩個點..+空格+后面的文本，代表注釋（網頁上不顯示）

等號線====+上一行的文本，代表一級標題

.. toctree::聲明的一個樹狀結構（Table of Content Tree）

:maxdepth: 2 表示頁面的級數最多顯示兩級

:caption: Contents: 用于指定標題文本（可以不要）

最下面的3行是索引和搜索鏈接（可以先不用管）

3.2.2 修改index文件

修改soure文件夾下的index.rst文件,，這里表示添加了一個Cpp目錄，然后Cpp目錄下，鏈接的又一個index文件

.. toctree:: :maxdepth: 3 :caption: Contents: Cpp/index

然后新建Cpp文件夾，并在該文件夾內新建若干個子類文件夾和一個index.rst文件，我新建的如下圖：

然后編輯soure/Cpp文件夾里的index.rst文件，這里表示該目錄級別下，又包含了3個子目錄，子目錄中再次通過index文件來描述子目錄中的文檔結構：

C++知識 ================================= .. toctree:: :maxdepth: 2 01設計模式/index 02數據結構/index 03多線程/index

然后再進入各個子文件夾，添加markdown格式的文檔和index.rst文件，這里以01設計模式文件夾為例：

soure/Cpp/01設計模式中的index.rst文件內容如下，這里表示管理了2個文檔

設計模式 ================================= .. toctree:: :maxdepth: 1 01單例模式 02工廠方法模式

具體的文檔，如01單例模式.md中，就可以記錄學習筆記了，示例如下：

# 單例模式 這是單例模式 ## 二級標題 這是單例模式

然后就可以編譯，查看效果了。

這是主頁的效果：

這是文檔的效果：

4 項目托管到gitee

以上的操作，只能在本地的瀏覽器查看文檔，若想讓所有人都能看到，需要部署到ReadtheDocs展示，在部署之前，要把代碼托管到代碼托管平臺，這里選用gitee，國內使用速度快。

先到gitee上（https://gitee.com/）建立一個公開的倉庫，然后將本地項目文件上傳即可，如我是建立一個名為SphinxDemo的倉庫。

在上傳文件之前，先自己寫一個.gitignore文件，用于指示編輯的文件（build目錄）不上傳到代碼倉庫，.gitignore文件內容如下：

build/

然后使用就是在本地的項目文件夾內使用基本的git指令來將文件上傳到倉庫：

git init git add -A git commit -m "first commit" git remote add origin https://gitee.com/xxpcb/sphinx-demo.git git push -u origin master

5 部署到ReadtheDocs展示

最后，就是借助ReadtheDocs平臺(https://readthedocs.org/)，將我們的項目分享展示。

選擇手動導入一個項目：

將gitee倉庫的HTTPS鏈接復制過來

填寫項目名稱，填寫gitee倉庫的HTTPS鏈接

然后就可以點擊Build version進行項目構建了

Build成功后，點擊閱讀文檔即可查看效果

https://sphinxdemotest.readthedocs.io/en/latest/

6 搭建過程演示視頻

https://www.bilibili.com/video/BV1S5411T7Qg

Git Sphinx

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。