[筆記] 關於 Git Submodule 建立主從儲庫的關聯

問題:

我有一個利用 Sphinx 建置的文檔專案,並已上傳至 GitHub。該文檔專案的 theme 是自行設計,並準備給多個文檔專案引用 (也就是共用),所以 theme 也是視為另一個專案,並也上傳至 GitHub。

這樣的作法可以確保爾後所有的文檔專案,都可以引用到最新版本的 theme,而不用個別採複製、覆蓋的方式來個別維護 theme 的檔案結構。

所以該如何讓文檔專案可以引用 theme 專案,建立關聯?

解決方案

利用 Git submodule 指令,讓該文檔專案將 theme 專案視為主專案內的子模組。

簡單作法:

閱讀全文 »

初識 Git∣GitHub-Git 簡史

Git[1]是由 Linux 之父-托瓦茲 (Linus Torvalds)為了維護 Linux 核心 (kernel)所開發出的版本控管工具。

早於 1991-2002 年間,當時 Linux 系統的核心維護,僅以補丁與備份性檔案 (patches and archived files)的方式實現。而後當 Linux 核心的維護規模日益龐大後,核心團隊決定與當時一家提供商業性版本控制系統-BitKeeper 合作,由其免費提供核心源碼的儲庫 (repository)。

這段蜜月期至 2005 年時,Linux 核心開源社群與 BitKeeper 結束長達三年的合作關係,而這也使得核心團隊必須著手開發屬於他們自己的版本控制工具。從 BitKeeper 的使用經驗中,他們制定了新的版本控制系統需要能達成下列幾個目標:

  • 速度。
  • 簡單設計。
  • 可以給予數以千計並行分支 (parallel branches)的非線性開發模式強力支援。
  • 完全分散式。
  • 能有效處理如 Linux 核心大型專案的規模 (速度與資料量的考量)。
  • Git 自 2005 年誕生以來,日益成熟且易於使用,而且還能維持原來的初衷-確實履行上述的目標設定;而最為人樂道的分散式架構,已證明更能有效應用在大型的協同式專案開發。有別於 CVS/Subversion 的中央集權控管方式,Git 可以不需要伺服器就可以在單機上運作版本控制,這也使得原始碼更容易發佈與分享。

    閱讀全文 »

關於線上文檔製作工具與管理相關機制摘記

目的:可便於在線上製作與編輯主控性文件 (具有大綱架構 (章、節)的 TOC (Table of Contents)文檔)。除了提供 HTML 格式的瀏覽,也可以轉換格式為 PDF, ePub/Mobi 等適於實體印刷與電子書格式。整理後的文檔可以容易上傳至 Hosting Server (網站/雲端空間),甚能具有版本控管與協同編輯撰寫的功能。

說明:原來為編寫 Python 線上文件而所開發以 Python 語言編寫的工具-Sphinx,已逐漸成為製作線上文件的最普及好用的免費開源工具。關於 Sphnix 的幾個主要特性:

  • 輸出格式:HTML (including Windows HTML Help), LaTeX (for printable PDF versions), Texinfo, manual pages, plain text。
  • 廣泛的交互參考 (cross-references):語義化的標記 (semantic markup),並對包括 函式、類別、引用文、術語詞彙表與類似片段資訊提供自動化的鏈接 (automatic links)。
  • 階層式的結構: 可輕鬆定義樹狀文件,並自動化鏈接同級/父級/下級 (siblings, parents and children)的文件。
  • 自動化的目錄: 產出與特定語言關聯的模組索引目錄。
  • 程式碼的處理:利用 Pygments highlighter 自動生成各程式語言的高亮度代碼區塊。
  • 擴展套件: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs) ...。

先瞧瞧一位大陸知名 IT 作者利用 Sphinx 所整理出很棒的線上文檔-GotGitHub,就可以看出 Sphinx 的強大功能。

另外一個參考展示-編寫《Redis 設計與實現》時用到的工具

閱讀全文 »

軟體思維顧問

專職軟體輔導與教育訓練的獨立顧問。輔導企業資訊單位如何有效組織系統開發與維護;輔導開發人員達成有效的專業分工。傳授如何把軟體作軟 (Keeping Software Soft)的技能,得以提昇系統的彈性/延展,並進而創造系統的再利用價值。

Personal