README

nochso/writeme是一个用于维护README和相关文件的PHP CLI工具。

例如，以下目录表是从WRITEME.md中的@toc@占位符生成的。

nochso/writeme
简介
安装
要求
使用方法
可用占位符
许可证

简介

writeme可以被认为是一个专注于典型Markdown文档（如readme、变更日志、项目文档等）的模板引擎。尽管它针对Markdown，但其他标记语言和纯文本也可以使用。

一个writeme文档可以包含YAML前文和文本内容

---
answer: 42
---
@answer@

前文占位符@answer@将在运行writeme <file>时转换为42。这是基本功能，但还有其他类型的占位符可以使用。

您甚至可以编写自己的，通过实现Placeholder接口。例如，每个占位符的文档都是自动从占位符类的PHPDocs生成的。这样，这个README就很容易更新。

安装

对于最终用户，PHAR版本更受欢迎。要全局安装

从最新版本下载PHAR文件。
使其可执行：chmod +x writeme.phar
将其移动到PATH中的某个位置：sudo cp writeme.phar /usr/local/bin/writeme

作为每个项目的本地Composer开发依赖项

composer require --dev nochso/writeme

作为全局Composer依赖项

composer global require nochso/writeme

要求

该项目是为PHP 5.6、7.0和HHVM编写的，并已进行测试。

使用方法

运行writeme

如果您已使用Composer在项目中引入了nochso/writeme，则可以运行位于vendor/bin的writeme可执行PHP文件

vendor/bin/writeme

不使用任何参数运行，以获取可用参数的概述。

初始化新模板

writeme附带一个典型的基于Composer的项目模板，可在Packagist上找到。您可以根据此模板初始化自己的WRITEME.md

writeme --init

只需回答问题。其中一些是可选的，按回车键将跳过它们或使用默认值。

一些占位符有默认设置：您将被询问是否要覆盖这些设置。然后，您的自定义设置将被添加到YAML前文中。

完成操作后，您应该有两个新文件。模板和结果输出，通常是WRITEME.md和README.md。

转义占位符

要避免替换占位符，请使用反斜杠转义@字符：\@example.escape\@。

指定目标文件名

默认情况下，名为WRITEME*的文件将保存为README*。所有大写或小写的名称都将保留。可以使用CLI选项--target <filename>或前文键target覆盖此默认行为

target: DOCS.md

可用占位符

前文 `@*@`

前文占位符返回前文中定义的值。

只要不与其他任何可用占位符的名称冲突，就可以定义任何类型的结构

---
greet: Hello
user:
    name: [Annyong, Tobias]
key.has.dots: yes
---
@greet@ @user.name.0@!
key has dots: @key\.has\.dots@

使用点符号访问前文值，结果如下所示

Hello Annyong!
key has dots: yes

在键本身中使用点符号是可能的，通过使用反斜杠转义它们。请参阅nochso/omni提供的Dot类。

`@*@`

目录 `@toc@`

TOC占位符从Markdown标题创建目录。

`@toc@`

收集文档中包含的所有Markdown标题，具有可配置的最大深度。

`@toc.sub($maxDepth)@`

@toc.sub@收集占位符下方以及同一级别或更深层级的Markdown标题。

如果占位符上方有标题，其深度将用作最小深度。如果占位符上方没有标题，则占位符后的第一个标题将用于最小深度。目前@toc.sub@没有最大深度限制。

例如：

# ignore me

@toc.sub@
## sub 1
# ignore me again

转换为：

# ignore me
- [sub 1](#sub-1)
## sub 1
# ignore me again

$maxDepth = 0 int
- 您希望保留的标题级别数。默认为零，表示保留所有子标题。

默认选项

toc:
    max-depth: 3

toc.max-depth
- 提取标题级别的最大深度。

API `@api@`

API从PHP代码创建文档。

默认情况下，它将在项目中搜索所有*.php文件，排除Composer vendor和test*文件夹。

可用的模板名称

summary - 带有PHPDocs第一行的缩进命名空间、类和方法的列表。
short - 带有PHPDocs第一行的缩进命名空间和类的列表。
full - 每个类和方法的详细文档。

`@api($templateName)@`

$templateName string
- 'summary', 'short'或'full'

默认选项

api:
    file: ['*.php']
    from: [.]
    folder-exclude: [vendor, test, tests]

api.file
- 要解析的文件模式列表。
api.from
- 要搜索文件的文件夹列表。
api.folder-exclude
- 要排除搜索的文件夹列表。

变更日志 `@changelog@`

更改日志从Markdown编写的更改日志中获取最新版本说明。

此占位符旨在用于遵循keep-a-changelog约定的更改日志。但是，它应该适用于任何格式化的Markdown发行版列表：每个发行版由Markdown标题标识。可以通过changelog.release-level选项指定哪种标题标记发行版。

`@changelog@`

默认选项

changelog:
    max-changes: 2
    release-level: 2
    shift-level: 0
    file: CHANGELOG.md
    search-depth: 2

changelog.max-changes
- 要包含的发行版数量。
changelog.release-level
- 代表发行版标题的标题级别。
changelog.shift-level
- 显示标题时添加的级别数。
changelog.file
- 要从中提取发行的更改日志的文件名。
changelog.search-depth
- 搜索文件夹的深度。

徽章 `@badge@`

`@image($imageUrl, $altText, $url)@`

$imageUrl string
- 徽章图像的URL。
$altText string
- 图像的替代文本。
$url = NULL string|null
- 可选的图像链接的URL。如果为null，则不创建链接。

`@badge($subject, $status, $color, $altText, $url)@`

通过shields.io创建徽章。

$subject string
- 徽章左侧的主题。
$status string
- 徽章右侧的状态。
$color = 'lightgrey' string
- 可选的状态颜色。默认为浅灰色。可以是任何十六进制颜色，例如0000FF或以下之一：brightgreen, green, yellowgreen, yellow, orange, red, lightgrey或blue。
$altText = NULL string|null
- 可选的图像替代文本。默认为subject - status。
$url = NULL string|null
- 可选的徽章链接的URL。如果为null，则不创建链接。

`@badge.writeme@`

提及writeme的额外徽章。

`@badge.travis($userRepository, $branch)@`

Travis CI构建状态。

$userRepository = NULL string|null
- 用户/存储库，例如nochso/writeme。默认为composer.name
$branch = NULL string|null
- 可选的分支名称。

`@badge.license($userRepository)@`

$userRepository = NULL

`@badge.scrutinizer($userRepository, $branch)@`

scrutinizer.

$userRepository = NULL null
- GitHub用户/仓库。
$branch = NULL null

`@badge.coveralls($userRepository, $branch)@`

$userRepository = NULL
$branch = NULL

`@badge.tag($userRepository)@`

$userRepository = NULL

许可证

nochso/writeme遵循MIT许可证发布。请参阅LICENSE获取完整的许可证文本。

nochso / writeme

维护者

详细信息

README

简介

安装

要求

使用方法

运行writeme

初始化新模板

转义占位符

指定目标文件名

可用占位符

前文 `@*@`

`@*@`

目录 `@toc@`

`@toc@`

`@toc.sub($maxDepth)@`

默认选项

API `@api@`

`@api($templateName)@`

默认选项

变更日志 `@changelog@`

`@changelog@`

默认选项

徽章 `@badge@`

`@image($imageUrl, $altText, $url)@`

`@badge($subject, $status, $color, $altText, $url)@`

`@badge.writeme@`

`@badge.travis($userRepository, $branch)@`

`@badge.license($userRepository)@`

`@badge.scrutinizer($userRepository, $branch)@`

`@badge.coveralls($userRepository, $branch)@`

`@badge.tag($userRepository)@`

许可证

nochso / writeme

维护者

详细信息

README

简介

安装

要求

使用方法

运行writeme

初始化新模板

转义占位符

指定目标文件名

可用占位符

前文 @*@

@*@

目录 @toc@

@toc@

@toc.sub($maxDepth)@

默认选项

API @api@

@api($templateName)@

默认选项

变更日志 @changelog@

@changelog@

默认选项

徽章 @badge@

@image($imageUrl, $altText, $url)@

@badge($subject, $status, $color, $altText, $url)@

@badge.writeme@

@badge.travis($userRepository, $branch)@

@badge.license($userRepository)@

@badge.scrutinizer($userRepository, $branch)@

@badge.coveralls($userRepository, $branch)@

@badge.tag($userRepository)@

许可证

前文 `@*@`

`@*@`

目录 `@toc@`

`@toc@`

`@toc.sub($maxDepth)@`

API `@api@`

`@api($templateName)@`

变更日志 `@changelog@`

`@changelog@`

徽章 `@badge@`

`@image($imageUrl, $altText, $url)@`

`@badge($subject, $status, $color, $altText, $url)@`

`@badge.writeme@`

`@badge.travis($userRepository, $branch)@`

`@badge.license($userRepository)@`

`@badge.scrutinizer($userRepository, $branch)@`

`@badge.coveralls($userRepository, $branch)@`

`@badge.tag($userRepository)@`