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

• Sphinx是一個功能強(qiáng)大的文檔生成器，具有許多用于編寫技術(shù)文檔的強(qiáng)大功能

• gitee是一種版本管理系統(tǒng)，相比github，有著更快的訪問速度

• Read the Docs是一個在線文檔托管服務(wù)， 你可以從各種版本控制系統(tǒng)中導(dǎo)入文檔

1 安裝環(huán)境

• Windows系統(tǒng)

• python3環(huán)境

2 Sphinx安裝與測試

2.1 基礎(chǔ)功能安裝

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

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

2.2 創(chuàng)建測試Demo

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

sphinx-quickstart

然后會有如下的輸出，需要根據(jù)提示輸入項目名稱、作者、版本號、語言等信息

G:\TestProject\sphinx\SphinxDemo>sphinx-quickstart Welcome to the Sphinx 4.0.2 quickstart utility.Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets).Selected root path: .You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: y <--------這里選y表示編譯的文件單獨放在build中The project name will occur in several places in the built documentation. > Project name: SphinxDemo <--------這里輸入項目的名稱 > Author name(s): xxpcb <--------這里輸入作者 > Project release []: v1.0 <--------這里輸入版本號If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language.For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: zh_CN <--------這里輸入語音（中文簡體）Creating file G:\TestProject\sphinx\SphinxDemo\source\conf.py. Creating file G:\TestProject\sphinx\SphinxDemo\source\index.rst. Creating file G:\TestProject\sphinx\SphinxDemo\Makefile. Creating file G:\TestProject\sphinx\SphinxDemo\make.bat.Finished: An initial directory structure has been created.You should now populate your master file G:\TestProject\sphinx\SphinxDemo\source\index.rst and create other documentation source files. Use the Makefile to build the docs, like so:make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.G:\TestProject\sphinx\SphinxDemo>

2.3 項目文件結(jié)構(gòu)

項目創(chuàng)建完成后，可以看到如下的目錄結(jié)構(gòu)：

進(jìn)入source文件夾，可以看到如下結(jié)構(gòu)：

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

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

• source: 存放文檔源文件

• • _static：靜態(tài)文件目錄，比如圖片等

  • _templates：模板目錄

  • conf.py：進(jìn)行 Sphinx 的配置，如主題配置等

  • index.rst：文檔項目起始文件，用于配置文檔的顯示結(jié)構(gòu)

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

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

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

2.4 普通編譯

執(zhí)行如下指令

make html

會輸出如下編譯結(jié)果：

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服務(wù)的方式，可以在瀏覽器器中通過ip地址來查看，該方式需要安裝自動build工具：

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

然后使用如下編譯指令進(jìn)行編譯

sphinx-autobuild source build/html

編譯結(jié)果如下：

然后可以到瀏覽器中，輸入<127.0.0.1:8000>查看效果：

2.6 更改樣式主題

上面的測試效果，使用的是默認(rèn)的主題alabaster，如果想安裝其它的主題，可以先到Sphinx的官網(wǎng)https://sphinx-themes.org/查看:

這里選用一個較為常用的主題Read the Docs，安裝這個主題首先需要在python中進(jìn)行安裝，命令如下：

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默認(rèn)只支持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 修改文檔顯示結(jié)構(gòu)

3.2.1 index文件分析

修改文檔結(jié)構(gòu)，需要修改index.rst文件，首先來看一下這個文件中的內(nèi)容：

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

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

• 等號線====+上一行的文本，代表一級標(biāo)題

• .. toctree::聲明的一個樹狀結(jié)構(gòu)（Table of Content Tree）

• :maxdepth: 2 表示頁面的級數(shù)最多顯示兩級

• :caption: Contents: 用于指定標(biāo)題文本（可以不要）

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

3.2.2 修改index文件

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

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

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

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

C++知識 =================================.. toctree:::maxdepth: 201設(shè)計模式/index02數(shù)據(jù)結(jié)構(gòu)/index03多線程/index

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

soure/Cpp/01設(shè)計模式中的index.rst文件內(nèi)容如下，這里表示管理了2個文檔設(shè)計模式 =================================.. toctree:::maxdepth: 101單例模式02工廠方法模式

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

# 單例模式這是單例模式## 二級標(biāo)題這是單例模式

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

這是主頁的效果：

這是文檔的效果：

4 項目托管到gitee

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

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

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

build/

然后使用就是在本地的項目文件夾內(nèi)使用基本的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/)，將我們的項目分享展示。

選擇手動導(dǎo)入一個項目：

將gitee倉庫的HTTPS鏈接復(fù)制過來

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

然后就可以點擊Build version進(jìn)行項目構(gòu)建了

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

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

6 搭建過程演示視頻

本文的模板工程已整理至我的gitee

點擊下方閱讀原文，可以直達(dá)此項目的gitee倉庫~

總結(jié)

以上是生活随笔為你收集整理的Sphinx+gitee+Read the Docs搭建在线文档系统的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。