README

简介

这是一个用于与 phpDocumentor 一起使用的自定义模板。

它的目的是创建代码文档的 markdown 文件，完全兼容于在 GitHub 仓库中作为 GitHub Wiki 使用。

示例

您可以在以下 GitHub 仓库中找到一个实时示例： zorgch/zorg-code/wiki

安装

1. 通过 composer composer require linchpin/phpdocumentor-template-markdown
2. 下载最新版本

先决条件

• phpDocumentor 必须已安装或可用，可以使用其 .phar
• 您已经将 GitHub Wiki 克隆到本地

从您的代码生成 GitHub Wiki Markdown

1. 使用 phpDocumentor 生成代码文档时指定此模板 phpdocumentor-template-markdown：php ./phpDocumentor.phar -d "/path/to/my/sourcecode" -t "/path/to/local/github-wiki" --template="/vendor/linchpin/phpdocumentor-template-markdown" --cache-folder "/path/to/store/cache" --title "My code project"

• 注意：您可能在解析结束时遇到错误 - 您可以忽略这个错误，所有工作都已经完成：ERROR In PathGenerator.php line 120: Variable substitution in path /namespaces/{{name}}.md failed, variable "name" did not return a value

1. 目标目录 /github-wiki 现在包含各种 markdown (.md) 文件
2. 审查、提交并推送您本地 GitHub Wiki 仓库的更改
3. 浏览到相应的 GitHub 仓库中的 Wiki，以在线查看您的代码文档

结果

考虑到 GitHub Wiki 页面处于扁平文件层次结构中。幸运的是，您仍然可以在仓库本身中使用文件夹 - 因此您可以在 Wiki 仓库中拥有干净的层次结构，但在链接文件时，它必须表现得像所有 Wiki 页面都在单个、扁平的层次结构中。

输出文件层次结构

输出包括以下文件层次结构

GitHub Wiki 页面处理

如前所述，由于 GitHub Wiki 页面不处于任何层次结构中，Wiki 页面之间的链接是...

• 通过引用页面的文件名来完成的
• 省略 .md 扩展名

所以使用 class-MyClass 链接到文件 /wiki/classes/class-MyClass.md。

或者 file-myconfigs.inc.php 链接到文件 /wiki/files/file-myconfigs.inc.php.md。