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

目的:可便於在線上製作與編輯主控性文件 (具有大綱架構 (章、節)的 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 設計與實現》時用到的工具


這裡先歸納整理幾個與 Sphinx 有關聯的機制:

  • Python:Sphinx 是利用 Pthon 語言撰寫的,所以系統必須要先安裝與設定好 Python 的編譯環境。
  • reStructuredText:它是一種輕量級的純文字標記語言,只利用簡單的文字編輯器即可撰寫文件,然後再利用 Sphinx 解析 (parse)並輸出包括 HTML 等上述所提及的文件格式。
  • Github:編譯後的文件可上傳至 GitHub 作為文件的版本管控系統,並可透過內建的 JekyII 生成靜態性的網站,或透過與外部的線上出版系統 (如下述的 Read the Docs)整合,而成為文檔的儲存資料來源。
  • Read the Docs:它是一個基於 Sphinx 的線上文檔託管系統,而且是開源免費的 (令人讚嘆與尊敬,該系統沒有任何營利行為)。Read the Docs 可以接收來自 Github, bitbucket 兩個商業性平台的版控資料源,也能支持包括 Mercurial, Git, Subversion, and Bazaar 等版控協定所建構的版控系統。

後續會再分享關於 Python, Sphinx @Windows-based 平台的安裝、設定摘要,並快速的利用 Sphinx 預設機制產出第一份線上文檔。

再來就是會把我個人 (以及團隊)多年來的文件與教材 (包括 Blog 文章),利用上述機制整理成線上文檔,而若有些內容實體出版商有興趣,也可以考慮與之合作,確實能出版為實體書籍。

文章導覽

   

發表迴響

你的電子郵件位址並不會被公開。 必要欄位標記為 *