最新博客鏈接 "Tsanfer's Blog"

創(chuàng)建Sphinx + GitHub + ReadtheDocs托管文檔

Readthedocs在線電子書鏈接

image

??????????????????????????????????

Sphinx	Github	Readthedocs
image

image

image

|

最終效果

image

Linux配置

Win10 Ubuntu子系統(tǒng)路徑：%USERNAME%\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79rhkp1fndgsc\LocalState\rootfs

更換Ubuntu源

step 1: 首先看看國內(nèi)有哪些源

step 2: 獲取 Ubuntu 代號

lsb_release -a

Ubuntu 18.04.1，查出來的代號就是 bionic.

step 3: 編輯源

image

紅色邊框：服務器地址

紫色邊框：Ubuntu 的代號（Codename）

step 4: 修改源文件 sources.list

先備份

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bcakup

再修改（如改為163源）

#163源
deb http://mirrors.163.com/ubuntu/ bionic main restricted universe multiverse
deb http://mirrors.163.com/ubuntu/ bionic-security main restricted universe multiverse
deb http://mirrors.163.com/ubuntu/ bionic-updates main restricted universe multiverse
deb http://mirrors.163.com/ubuntu/ bionic-proposed main restricted universe multiverse

##測試版源
deb http://mirrors.163.com/ubuntu/ bionic-backports main restricted universe multiverse

# 源碼
deb-src http://mirrors.163.com/ubuntu/ bionic main restricted universe multiverse
deb-src http://mirrors.163.com/ubuntu/ bionic-security main restricted universe multiverse
deb-src http://mirrors.163.com/ubuntu/ bionic-updates main restricted universe multiverse
deb-src http://mirrors.163.com/ubuntu/ bionic-proposed main restricted universe multiverse

##測試版源
deb-src http://mirrors.163.com/ubuntu/ bionic-backports main restricted universe multiverse

step 5: 更新軟件列表和升級

更新軟件列表（檢測出可更新的軟件）：

sudo apt update

更新軟件：

sudo apt upgrade

安裝Python3、pip

# 安裝python3
sudo apt install python3
# 安裝pip
sudo apt install python3-pip

更換pip源

pip國內(nèi)的一些鏡像

修改 ~/.pip/pip.conf (沒有就創(chuàng)建一個)， 內(nèi)容如下：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host=mirrors.aliyun.com

Github配置

克隆 一個新的公共的空白倉庫到本地 ~\Sphinx_GitHub_ReadtheDocs

目錄結(jié)構(gòu)：

.
├── LICENSE
└── README.md

Sphinx配置

安裝Sphinx、及其插件

pip3 install sphinx sphinx_rtd_theme recommonmark sphinx-markdown-tables sphinxemoji

初始化Sphinx

# 進入Git根目錄
cd ~/Sphinx_GitHub_ReadtheDocs
# 開始快速配置sphinx
sphinx-quickstart

# 選擇把源文件和刪除文件分開（y）
> Separate source and build directories (y/n) [n]:y
# 項目名稱
> Project name: Sphinx_GitHub_ReadtheDocs
# 作者姓名
> Author name(s): Tsanfer
# 版本號
> Project release []: 0.2
# 語言
> Project language [en]: zh_CN

目錄結(jié)構(gòu)：

.
├── LICENSE
├── Makefile
├── README.md
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

驗證配置是否正確：

cd ~/Sphinx_GitHub_ReadtheDocs
make html

瀏覽器打開./build/index.html查看

配置Sphinx主題，插件

配置./source/conf.py配置文件：

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.

extensions = [
        'recommonmark',
        'sphinx_markdown_tables',
        'sphinxemoji.sphinxemoji',
]

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# The master toctree document.
master_doc = 'index'

添加./requirements.txt pip要求文件（Readthedocs配置時需要用到）

# markdown suport
recommonmark
# markdown table suport
sphinx-markdown-tables
#emoji
sphinxemoji

# theme default rtd

# crate-docs-theme
sphinx-rtd-theme

更改標題，添加目錄，添加文件

配置./source/index.rst文件：

創(chuàng)建Sphinx + GitHub + ReadtheDocs托管文檔
=====================================================

.. toctree::
   :maxdepth: 2
   :numbered:

   Sphinx_GitHub_ReadtheDocs

創(chuàng)建./source/Sphinx_GitHub_ReadtheDocs.md文件

# here is a test markdown file

然后同步到Github

Readthedocs配置

image

指定pip要求文件: ./requirements.txt

image

完成

本文由Tsanfer's Blog 發(fā)布！