@20200115
官網
Sphinx 是 Sql Phrase Index （查詢詞組索引）的縮寫，Sphinx 是一個基於 Sql 的全文檢索引擎。
引用一段 Sphinx 生成文檔的優點包括：
豐富的輸出格式：支持輸出爲 HTML，LaTeX (可轉換爲PDF)， manual pages(man), 純文本等若干種格式
完備的交叉引用：語義化的標籤，並對函式，類，引文，術語以及類似片段消息可以自動化鏈接
明晰的分層結構：輕鬆定義文檔樹，並自動化鏈接同級/父級/下級文章
美觀的自動索引：可自動生成美觀的模塊索引
精確的語法高亮：基於 Pygments 自動生成語法高亮
開放的擴展：支持代碼塊的自動測試，自動包含 Python 的模塊自述文檔
全文檢索分兩個過程
索引創建（Indexing）和搜索索引（Search）
索引創建：將現實世界中所有的結構化和非結構化數據提取信息，創建索引的過程
搜索索引：得到用戶的查詢請求，搜索創建的索引，然後返回結果的過程
http://www.sphinx-doc.org/en/master/
配置文檔
https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
環境
CentOS-7.4
Python 3.5+
pip
nginx
mysql-8
安裝
# 安裝 python3
yum install python3
# 安裝 pip
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py
# 更換 pip 源
pip install psm --trusted-host mirrors.aliyun.com
psm ls
psm use qinghua
# 更換虛擬環境中的源
vi /root/Pipfile
[[source]]
name = "pypi-tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
verify_ssl = true
# 安裝 Sphinx
yum install python-sphinx
pip install sphinx sphinx-autobuild sphinx_rtd_theme
sphinx-build --version
初始化
mkdir /var/www/Sphinx
cd /var/www/Sphinx
sphinx-quickstart
type【也可以再編輯 vi conf.py 】
> 獨立的源文件和構建目錄（y/n） [n]: y
> 項目名稱: Sphinx
> 作者名稱: UXmall
> 項目發行版本 []: 0.1
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language
> 項目語種 [en]: zh_CN
目錄結構
# tree
.
├── build # 文件夾，當你執行 make html 的時候，生成的 html 靜態文件都存放在這裏
├── make.bat # 文件，
├── Makefile # 文件，編譯用，make 命令時，可以使用這些指令來構建文檔輸出
└── source # 文件夾，文檔源文件全部應全部放在 source 根目錄下
├── conf.py # 文件，Sphinx 的配置文件，是 read the docs 的配置文件；
├── index.rst # 文件，網站首頁
├── _static # 文件夾，_static 是放置一些圖片或者其他文件；
└── _templates # 文件夾，
功能
開啓 sys 和 os 模塊
vim conf.py
* 配置主題
html_theme = 'alabaster'
* 支持 LaTeX
* 支持中文檢索
extensions = ['chinese_search']
source_suffix = ['.rst', '.md']
【安裝】pandoc
yum install pandoc
利用 pandoc 轉換文件
利用 pandoc 將之前的 markdown 格式的博客源文件轉換成 rst 格式
# 語法
pandoc -s -t rst --toc markdown.md -o index.rst
#
pandoc -s -t rst --toc myshell-note.md -o myshell-note.rst
ls
conf.py index.rst myshell-note.md myshell-note.rst _static _templates
編輯 index.rst，進行引用文件
.. toctree::
:maxdepth: 2
:caption: Contents:
myshell-note
【生成 PDF】
# 安裝依賴庫
pip install rst2pdf
# 編輯 conf.py，增加或修改如下配置：
vi conf.py
# 編輯 Makefile，增加如下代碼：
vi Makefile
# 執行生成PDF
make pdf
python -m SimpleHTTPServer 9527
【生成 Slide】
# 安裝依賴庫
pip install hieroglyph
# 編輯 conf.py，修改如下配置：
vi conf.py
# 編輯 Makefile，增加如下代碼：
vi Makefile
#執行生成 Slides
make slides
python -m SimpleHTTPServer 9527
配置
_build # 存放最終構建生成的靜態html頁面
_static # 存放圖片、logo等相關資源文件
_templates # 存放模板文件
conf.py # 項目配置文件
index.rst # 文檔首頁
make.bat # windows下的構建腳本
Makefile # linux下的構建腳本
Makefile
編譯過代碼的開發人員應該非常熟悉這個文件，如果不熟悉，那麼可以將它看作是一個包含指令的文件，在使用 make 命令時，可以使用這些指令來構建文檔輸出。
_build
這是觸發特定輸出後用來存放所生成的文件的目錄。
_static
所有不屬於源代碼（如圖像）一部分的文件均存放於此處，稍後會在構建目錄中將它們鏈接在一起。
conf.py
這是一個 Python 文件，用於存放 Sphinx 的配置值，包括在終端執行 sphinx-quickstart 時選中的那些值。
index.rst
文檔項目的 root 目錄。如果將文檔劃分爲其他文件，該目錄會連接這些文件。
This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.
Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles.
Lists can be unnumbered like:
* Item Foo
* Item Bar
Or automatically numbered:
#. Item 1
#. Item 2
Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo``
gives you super user powers!
概念
source
數據源，數據是從什麼地方來的。
index
索引，當有數據源之後，從數據源處構建索引。索引實際上就是相當於一個字典檢索。有了整本字典內容以後，纔會有字典檢索。
searchd
提供搜索查詢服務。它一般是以deamon的形式運行在後臺的。
indexer
構建索引的服務。當要重新構建索引的時候，就是調用indexer這個命令。
attr
屬性，屬性是存在索引中的，它不進行全文索引，但是可以用於過濾和排序。
修改主題
主題一
# Sphinx 提供三個主題 默認主題 alabaster
# 安裝 sphinx_rtd_theme 主題
pip install sphinx_rtd_theme
# 在 conf.py 之中更改主題
#
#
vi conf.py
import sphinx_rtd_theme
extensions = [
...
"sphinx_rtd_theme",
]
html_theme = "sphinx_rtd_theme"
主題二
# Sphinx 提供三個主題 默認主題 alabaster
# 安裝 sphinx-better-theme 主題
pip install sphinx-better-theme
# 在 conf.py 之中更改主題
#
#
vi conf.py
import sphinx_rtd_theme
extensions = [
...
"sphinx-better-theme",
]
html_theme = "sphinx-better-theme"
主題三
# Sphinx 提供三個主題 默認主題 alabaster
# 安裝 sphinx-bootstrap-theme 主題
pip install sphinx-bootstrap-theme
# 在 conf.py 之中更改主題
#
#
vi conf.py
import sphinx_rtd_theme
extensions = [
...
"'sphinx-bootstrap-theme'",
]
html_theme = "'sphinx-bootstrap-theme'"
配置 logo
# 在 conf.py 之中指定 logo 圖片 ,相對於 conf.py 的文件路徑
vi conf.py
html_logo = './_static/logo.jpg'
配置文檔自動生成
vi conf.py
extensions = ['sphinx.ext.autodoc']
# 然後在需要的頁面中添加
vi index.rst
.. automodule:: my_package
:members:
# my_package 爲代碼的報名，有了這樣的配置在生成文檔時會向* :ref:modindex 指向的包索引頁面中添加相應的索引
# 注：autodoc 是自動生成的，如果需要手動生成，可以使用 sphinx-apidoc 這個命令來完成
定義文檔結構
https://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html#id1
vi index.rst
有兩個文本 file1.rst 和 file2.rst 他們的內容如下
添加內容
運行創建工具
sphinx-build -b html sourcedir builddir
sphinx-build -b html ~/Sphinx/sourcedir /var/www/UXmallSphinx
make html
文檔對象
基本配置
自動文檔
其他
參考：
http://zhengkun.info/2014/02/10/sphinx-doc/
http://www.pythondoc.com/sphinx/rest.html
https://www.cnblogs.com/xiaofan1949/p/10497813.html
