文件編寫工具-sphinx¶
長期以來靠網路取得工作的知識,最近想要把腦中學過知識寫成書放在網站上面,給自已及需要的人看,於是上網找看看有沒有適合的工具使用. 於是發現 sphinx 這套工具,仔細的研究一下還蠻好用的,本網站的所有文件開發就是用 sphinx 工具所開發的.當然包含了本頁. sphinx 是一套好用的工具,它有下面陳列的幾項特色:
- 輸出格式(Output formats):HTML,(for printable PDF versions), ePub, Texinfo, manual pages, plain text
- Extensive cross-references:語意標記並且可自動鏈結函數(function),類別(classes),引用(citations),術語字彙(glossary terms),similar pieces of information
- 階層結構(Hierarchical structure):簡易定義樹狀階層,自動鏈結上下文及前後文.
- 自動索引(Automatic indices):一般索引以及特定於語言的模塊索引
- 程式碼處理(Code handling):自動突出顯示,使用 Pygments highlighter.( _Pygments 是各種語言的語法突出顯示)
- 擴展(Extensions):自動測試代碼片段，包含Python模塊中的文檔字符串（API文檔）, 更多參考
- 貢獻擴展(Contributed extensions):用戶在第二個存儲庫中貢獻的超過50個擴展; 其中大多數可以從PyPI安裝
內文章節
- 1. 安裝 sphinx
- 2. 文件檔案專案
- 2.1. 執行sphinx-quickstart指令
- 2.1.1. 原始與建置目錄是否分離
- 2.1.2. templates程static目錄前置符號
- 2.1.3. 專案名稱
- 2.1.4. 專案語言
- 2.1.5. 原始檔附檔名
- 2.1.6. 首頁文件名稱設定
- 2.1.7. 插入docstrings模組
- 2.1.8. 自動測試碼片段
- 2.1.9. 聯結不同專案
- 2.1.10. todo顯示或隱藏
- 2.1.11. 檢查文檔覆蓋率
- 2.1.12. 包含數學-PNG或SVN圖片呈現
- 2.1.13. 包含數學-瀏覽器從MathJax呈現
- 2.1.14. 條件式配置
- 2.1.15. 檢示程式碼
- 2.1.16. github 發怖
- 2.1.17. 建立Makfile檔案
- 2.1.18. 建立批次檔
- 2.1.19. 完成文檔案建置
- 2.1.20. conf設定檔
- 2.2. 建立文檔html
- 2.3. 設定html 主題(theme)
- 2.1. 執行sphinx-quickstart指令
- 3. reStructuredText 介紹
- 3.1. 定義文件結構
- 3.2. 區段章節設定
- 3.3. 內文標記(Inline markup)
- 3.4. 清單和引用 區塊(list and Quote-like)
- 3.5. 文字區塊(Literal blocks)
- 3.6. python文件測試區塊(Doctest blocks)
- 3.7. 表格(Tables)
- 3.8. 欄位清單(Field Lists)
- 3.9. 角色(Roles)
- 3.10. 指令(Directives)
- 3.11. 注腳(Footnotes)
- 3.12. 引用文(Citations)
- 3.13. 取代(Substitutions)
- 3.14. 備註(Comments)
- 4. 使用eclipse IDE 編寫