WISE-PaaS文件(Documentation)系統 - 說明文件
此文件的目的
讓各位無痛上手編輯自行負責的產品(服務)文件並維護
甚麼是WISE-PaaS文件系統?
WISE-PaaS Technical Portal上會羅列所有WISE-PaaS相關服務的文件，不過有鑑於目前沒有一個統一的文件管理系統，WISE-PaaS文件系統於焉誕生。WISE-PaaS文件系統使用的是位於GitHub上的一個開源專案MDWiki。
MDWiki是一個只要編輯Markdown文件便會自行產生單頁式網頁的文件系統。以下是MDWiki的幾個特點:
- 支援響應式設計(RWD)
- 不需要另外架伺服器，由於只是靜態文件，它可以直接架在GitHub或是GitLab上，並透過Pages的功能產生網頁
- 內建多種UI主題供網頁瀏覽者自行選擇
- 使用簡單易學的
Markdown編輯文件 - 創造統一的文件格式(文件下方會詳細介紹Markdown特性)
- 支援語系切換
WISE-PaaS文件系統架構
WISE-PaaS文件系統 = MDWiki + Gitlab Pages(.gitlab-ci.yml + Runner)(Auto Deployment)
簡而言之，一旦提交至master branch，Gitlab Pages CI流程會自然啟動(Runner會去執行.gitlab-ci.yml的內容達到Auto Deployment的功能)(CI流程會需要幾秒至幾分鐘時間)
WISE-PaaS文件系統檔案架構
- documents(#)
- Each service has its folder
- uploads
- images
- Each service has its folder
- apidoc(#)
- Each service has its folder
- lib
- css
- bootstrap.min.css
- github.min.css
- js
- bootstrap.min.js
- highlight.min.js
- jquery.min.js
- .gitattributes
- .gitignore
- .gitlab-ci.yml
- config.json
- WISE-PaaS Documentation.pdf
- index.html
- index.md(#)
- navigation.md(#)
- README.md(#)
- slide.md
- WISE-paas.md
- WISE-paas.jpg說明
#:表示各位需要注意的檔案
-
documents: 各服務(產品)各占一個資料夾，例如RMM，SCADA就需要兩個資料夾。命名幾乎仿照WISE-PaaS Technical Portal上命名。 -
images: 裏頭一樣各服務(產品)各占一個資料夾。 -
apidoc: 裏頭定義各服務(產品)的API文件。 -
README.md: 即此檔案。 -
index.md: WISE-PaaS文件系統首頁，目前是WISE-Paas 快速指南。 -
navigation.md: 這是大家都會接觸到的唯一檔案，這裡頭定義網站內的navigation bar內容。請注意，即使寫完documents，若沒有更新navigation.md，WISE-PaaS文件系統仍然無法出現新增的documents。即navigation.md定義使用者如何瀏覽我們編輯好的documents。
常見使用流程
強烈建議在local端編輯再push至master
Q1: 已有文件在WISE-PaaS文件系統中，那麼要如何更新文件內容? (註: 編輯並儲存後即生效)
A1:
(直接在Gitlab上編輯)
- 編輯文件(Edit)
- 預覽(Preview)
- 填寫更新備註(Commit message)
- 儲存(Commit Changes)
(在Local端先編輯)
git pull- 編輯文件，預覽
- commit and push至master
Q2: 如果尚無文件在WISE-PaaS文件系統中，那麼要如何更新文件內容? (註: 請記得最後要更新navigation.md)
A2:
(在Local端先編輯)
git pull- 若尚無此產品(服務)的說明文件，請先在
documents下及documents/uploads/images下各自新增資料夾( 名稱即是該產品(服務)，建議兩者相同 ) - 編輯文件(Edit)，若文件需要圖片，請將圖片上傳至
documents/uploads/images/[新資料夾]下，並將文件中各圖片的url相對應至正確的位置。( 請使用Relative Path，下方會詳細說明 )，預覽(Preview) - 更新
navigation.md( 方法於下方詳細說明 ) - commit and push至master
Local端開發工具推薦：
- MarkdownPad2: Markdown Editor (Windows)
- MacDown: Markdown Editor (Mac)
- Fenix: Static Desktop Web Server (Windows, Mac)
文件格式
為了要讓WISE-PaaS文件系統達成一致的UI風格，請務必遵守以下格式(以下語法皆是Markdown語法)
- 文件標題下請加上這串符號(
===)。 - 文件可分成多個段落(section)，在段落標題下請加上這串符號(
---)，標示段落可以讓網頁瀏覽者快速導覽文件，更利於他們了解文件內容。 - 若需要在條列項中插入圖片，請使用無序種類，即bullet list。
-
Markdown很注重空行，尤其是各元素之間。(例如: 一段文字與條列項之間需要空行)請多注意(多使用預覽功能) - 若使用
Markdown的Table元素，使用預覽功能時會發現Table與其他元素之間會有大段空白，此為正常現象。 - 假設你在
documents/RMM/userguide.md中需要一張圖片(01.jpg)，若這張圖片目前在documents/uploads/images/RMM下，則文件中你需要填入。 - Code highlight方法請見Syntax highlighting，另外縮排請一律以兩格空白為標準。
- API Document編輯方法:
- 請在對應的
apidoc/[Service Name]/資料夾下新增api.md - 請在
api.md內新增<iframe frameBorder="0" src="http://api-XXX.wise-paas.com" style="width: 100%; height: 100vh; overflow: auto;" />(請注意：此功能無法使用預覽功能)-
請先確認能否將api-XXX.wise-paas.com的連結嵌入於iframe中
a. 可以 -> 保留api.md，文件系統內的API文件便可刪除
b. 不行 -> 這是因為Http header中的X-Frame-Options不允許文件系統存取資源，請將X-Frame-Options修改成 ALLOW-FROM http://ei-paas-documentation.docs.wise-paas.com/Documentation/*
-
- 請在
navigation.md內更改apidoc的讀取路徑，以RMM為例：更改成[API](apidoc/RMM/api.md)
- 請在對應的