php markdown 接口文檔生成工具 SummerDoc

2017年9月18日 19:20:22 星期一

因工作需要, 用PHP寫了一個管理接口文檔的小工具, 下邊介紹一下:

瀏覽器展示的效果:

項目地址:(碼雲)

例子(http://doc.hearu.top/)

項目模塊說明:

1. 左側目錄樹: dtree.js  不依賴其他js
2. Markdown轉html: segmentfault社區開發的PHP工具 parsedown  (一個國外的PHP類)
3. 遍歷md文件生成左側目錄樹所需的數據: 利用樹的后根序遍歷算法讀取文件夾的PHP類(自己開發, 暫未發現bug)

特點描述:

1. 左側目錄會根據當前頁面的不同, 自動展開並高亮
2. 目錄是根據文件夾/文件名自動生成的, 無需另外編寫
3. 使用markdown編寫, 只用編寫主體內容
4. 風格類似github, 鼠標放在表格的行上時會高亮
5. 若表格內換行需要手動寫 <br>
6. 文檔的最下邊顯示最后編輯時間
7. 手機(自測用的4.7寸瀏覽器)可自適應縮小

使用說明:

1. 需要安裝 PHP 最好是7.1+以上的版本
2. 將md文件放入src目錄里, 按照自己的項目命名文件和文件夾(這些名字就是最終生成的左側樹形目錄的名字)
3. 進入根目錄, 運行命令: php compile.php  之后就可以在_book目錄里看到編譯好的html文件了
4. 在web服務器中搭建一個虛擬機(比如: doc.abc.com), 並將根目錄設置為 _book, 重啟后在瀏覽器里訪問

注意:

1. _book目錄里的dtree目錄是事先寫好的css和js, 對dtree的源文件有一些簡單的改動, 
2. 如果不小心刪掉了, 可以到根目錄里解壓dtree.zip, 復制到_book文件夾中
3. 如果想重新編譯所有文件, 可以刪掉根目錄下的 last_compile_time.log 文件, 不然, 程序只會編譯最新修改的文件

小技巧:

如果不想每次提交前都手動執行 `php compile.php` 命令去編譯md文件, 可以利用 Git 或 SVN 的 hook 功能去自動執行這個命令:

下邊以 小海龜git為例, 給git加hook腳本:

 2018-2-10 15:51:28 星期六 更新

nginx 服務器虛擬機配置:

server {
        listen       80;
        server_name  www.markdown.com;
        
        autoindex on;
        location / {
            root E:\virtualbox\PHP-Summer-Doc\_book;
            fastcgi_index  index.html;
        }

    }

2018-2-9 15:32:18 星期五 更新

因為sf出的md解析器在處理單行多個 <br> 的時候會間隔處理, 所以替換了另一款解析器類 parsedown.php 

這個比較快, 但他官方說明沒有進行安全校驗, 如果擔心安全問題要使用其他插件幫助處理一下, 以下是官方說明

Security

Parsedown does not sanitize the HTML that it generates. When you deal with untrusted content (ex: user comments) you should also use a HTML sanitizer like HTML Purifier.