這段時間準備軟考去了，也挺久沒更新了，考完了（明年再戰...），可以開始繼續這個系列了。
前面1篇是程式碼檢查方面，這一篇主要講一下如何用Gitlab來託管我們的專案文件，我接觸到的專案文件一般有下面幾種方式：
- 放在wiki裡面：這種方式有個缺點就是不方便分享文件，也不好把文件轉成其他格式
- 以markdown的形式和專案放在一起：這種方式應該算是使用方式比較廣的了，很多開源專案也是這種。如果只是這麼放著，看文件其實不是很方便，缺乏文件之間的導航。
- 使用Read the Docs 託管文件
本篇文章比較類似於第三種，就是用Gitlab Pages來實現類似Read the Docs的效果：
1.什麼是Gitlab Pages
按照官方解釋Gitlab Pages是用Go寫的一個Http伺服器，通過它可以很方便的通過Gitlab專案託管靜態網頁。這個功能對我們來說就是我們可以通過Gitlab很方便的託管我們的文件，只要我們把他們轉換成靜態的網頁就好。
2.開啟Gitlab Pages
這個功能預設並沒有開啟，需要我們開啟，修改gitlab所在伺服器的gitlab.rb設定，主要是下面的選項：
pages_external_url 'http://example.io' ###設定pages的域名，生成的網站地址就是 http://username或groupname/example.io/projectname
gitlab_pages['enable'] = true
3.基本過程
託管還是通過Gitlab runner來完成的，因此還是需要寫.gitlab-ci.yml檔案來實現，pages的job有自己的job名，就叫'pages', 大概就像下面這樣：
pages:
stage: deploy
script:
- cp *.html public
only:
- master
主要操作就是將要託管的網頁（包含一個index.html的主頁）拷貝到public目錄。Pages託管的其實是public目錄中的網頁。一個最簡單的例子：https://gitlab.com/gitlab-gold/a.conrad-test/pages
4.託管markdown文件
通過第三章的方式，我們可以託管網頁了，但是我們很多文件其實並不是網頁，而是markdown。如果需要手動生成網頁再去託管，其實還是挺不方便的，因此我們還是需要一些轉換方式，能夠把我們的markdown文件在構建的時候自動轉換成html。好在markdown轉換html有比較成熟的方式, 而且也能根據需要按不同的主題風格去生成，比如上文提到的read the docs其實也是一種主題。轉換的工具主要有sphinx, mkdocs等，mkdocs相對比較簡單，純粹基於markdown實現，也有很多外掛可以完成各種各樣的需求。而sphinx支援rst和markdown,在某些需要通過rst控制格式的情況下，會更方便，本文使用sphinx。
4.1 安裝sphinx等依賴
除了sphinx，為了更好使用，還會安裝主題和其他外掛，這些依賴是安裝在Gitlab-runner所在的伺服器，而不是Gitlab服務。
pip install sphinx sphinx-rtd-theme recommonmark readthedocs-sphinx-search sphinx_markdown_tables
4.2 配置專案的sphinx配置
sphinx是通過專案下的conf.py來決定生成什麼樣的網頁。conf.py即可以手動建立，也可以通過
sphinx-quickstart
先生成一個模板。根據專案需要進行配置, 本文用的：
# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
import sphinx_rtd_theme
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
# -- Project information -----------------------------------------------------
project = u'AlgorithmDocs' ##專案名
copyright = u'2020, Uniubi Vision Lab' ##版權資訊
author = u'Uniubi Vision Lab' ##作者
# The short X.Y version
version = u'1.0' ##版本
# The full version, including alpha/beta/rc tags
release = u''
# -- 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','sphinx_search.extension'] ##外掛
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md'] ##文件的字尾
# The master toctree document.
master_doc = 'index' ##首頁檔案的名稱
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- 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' ##主題，rtd就是read the docs主題
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'AlgorithmDocs'
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
4.3 編寫專案文件
可以用rst或者markdown進行編寫，假設我們的專案是多個專案的文件集合（文件和程式碼放一起的其實類似）。專案目錄結構大概這樣：
ProjectDocs
├── README.md
├── conf.py
├── project1
│ └── doc1.md
├── project2
│ └── doc2.md
├── project3
│ └── doc3.md
4.4 建立首頁索引
在專案下新建index.rst檔案，這個檔案的作用就是作為生成出的網頁的主頁，用來索引各個子頁面。
可能我們並不熟悉rst語法，不過不用擔心，只是寫這個頁面的話不需要非常熟悉, 只要參考下面這個寫就好：
演算法文件
=================
.. toctree:: ##一個章節或一個專案
:maxdepth: 1 ##顯示到第幾級標題，對應markdown檔案中的標題
:caption: project1 ##章節名或者專案名
project1/doc1 ##具體的文件
.. toctree:: ##一個章節或一個專案
:maxdepth: 1 ##顯示到第幾級標題，對應markdown檔案中的標題
:caption: project2 ##章節名或者專案名
project2/doc2 ##具體的文件
若對文件有異議或需求，請反饋至：
http://XXX
4.5 配置gitlab-ci.yml
配置gitlab-ci.yml，根據我們的配置去生成網頁並託管，其實就是執行sphinx的生成網頁命令，放到public目錄即可：
pages:
stage: deploy
script:
- sphinx-build -b html . public ##呼叫sphix-build來生成html網頁
artifacts:
paths:
- public
only:
- master
有時候我們想把自己生成的網頁整個下載下來，這個可以通過gitlab的artifacts機制，也就是上面配置檔案的artifacts設定，就可以在Pipeline或jobs介面看到下載按鈕，後面講到為了方便除錯也會用到這個功能：
4.6 生成網頁
當我們把寫好的文件合入master分支，就會觸發gitlab-ci去自動生成網頁並託管，生成的網頁地址可以在專案的Pages頁面看到：
4.7 配置DNS或者hosts檔案
雖然生成了網頁，不過我們可能會發現並不能訪問，這主要是由於生成的域名無法正確解析到我們的伺服器上，可以通過修改我們本地的hosts檔案，將我們的域名重定向到gitlab伺服器。更好的方式是由運維把域名加入到DNS伺服器中，注意加的時候進行通配操作，比如把http://groupname.pages.io字首開頭的全部重定向，這樣我們再在這個groupname下建立其他專案，也都可以訪問了。
通過上述操作，我們就生成了可訪問的文件網頁，如下：
原始的專案結構：
5.預覽和除錯
在寫完文件之後，我們需要預覽一下生成的頁面才確定是否能夠往主分支合入，有下面幾種方式：
5.1 直接使用sphinx命令生成網頁
sphinx-build -b html . public ##呼叫sphix-build來生成html網頁
然後開啟index.html檔案即可。
5.2 VScode+sphinx外掛預覽
前提條件也是需要本地安裝好python，前文中提到的sphinx。開啟VScode，會提示安裝對應外掛，就可以預覽生成的網頁了，其實應該也是呼叫樂sphinx-build。
5.3 下載Gitlab生成的網頁
前面兩種方式都要求每個寫文件的人，要本地搭建sphinx等依賴，雖然也可以通過遠端到gitlab-ci伺服器，但終究也是非正常的行為。還有一種方式就是利用Gitlab的artifacts，實現提供下載生成的網頁的功能（4.5）。為了方便測試，我們要提供在非master分支生成網頁的功能，只需要在gitlab-ci.yml檔案中加入一個普通的job即可：
test:### 實現在提交內容到非主分支時也生成網頁並提供下載
stage: test
script:
- sphinx-build -b html . public
only:
- branches
artifacts:
paths:
- public
except:
- master
pages:
stage: deploy
script:
- sphinx-build -b html . public
artifacts:
paths:
- public
only:
- master
總結
通過Gitlab pages實現的靜態網頁服務功能，既可以用於個人搭部落格，也可以用於專案或團隊文件的管理、呈現方式，生成的網頁可以很方便的在內部進行分享。結合其他開源工具，還可以實現文件轉word, 更進一步的再轉換成pdf, 這一部分就下次再總結了。