README

代码涂鸦

代码涂鸦是一个文档生成器。您编写 .src.md 文件，并在其中使用 @‌verbs() 调用内置函数，包括 @‌template(template_name) 以加载多个内置模板。您可以为自己的项目创建自定义扩展和模板，或者为使用您创建的库生成文档。

还可以生成 PHP 类的完整 API 文档。AST 生成使用 taeluf/lexer，可以扩展以支持其他语言，但截至 2023 年 5 月，还没有明确的计划这么做。

功能

集成 AST 生成，自动复制粘贴源代码的特定部分，归功于 php/lexer
多个内置动词和模板
通过自定义动词和模板进行扩展。

弃用警告

v1.0 将停止使用隐藏目录如 .docsrc/，而是使用 docsrc/。defaults.json 文件将在 v1.0 中进行更改以适应。
v1.0 将使用目录 src/ 而不是 code/ 作为默认扫描目录。（目前也扫描 test/，这不会改变）

文档（以下）

安装
配置
- 默认值
- 扩展
用法
- 示例文档
- @verb()（本质上为函数）
- 模板
- 生成变更日志
扩展
- 模板
- 动词 / 动词处理程序
- 类
架构
附加信息

安装

选择一个

composer require taeluf/code-scrawl v0.8.x-dev
composer require taeluf/code-scrawl {latest_version} - see Versions
PHAR（实验性）：设置版本，然后使用 curl 下载 phar 文件。
1. v="0.X.Y.Z" - See Versions
2. curl -o scrawl.phar https://gitlab.com/taeluf/php/CodeScrawl/-/raw/$v/bin/scrawl.phar?inline=false

版本号：0.X.Y.Z，0.X 来自分支名称，Y 在添加功能时增加，Z 在修复错误和某些其他更改时增加。（此版本由 'feature:'、'bugfix:' 或 'other:' 的提交消息前缀确定。如果 Y 增加，则 Z 设置为 0。）

配置

在 config/scrawl.json、.config/scrawl.json 或 .docsrc/scrawl.json 中创建一个文件。

默认值

{  
    "--NOTICE":"v1.0 will introduce updated defaults.",  
    "--docs_url--": "https://www.taeluf.com/docs/Code%20Scrawl or https://gitlab.com/taeluf/php/CodeScrawl",  
  
    "template.dirs": [".doctemplate"],  
  
    "dir.docs": "docs",  
    "dir.src": ".docsrc",  
    "dir.scan": ["code", "test"],  
    "ScrawlExtensions":[],  
  
    "file.bootstrap":"scrawl-bootstrap.php",  
  
    "api.output_dir": "api/",  
    "api.generate_readme": true,  
  
    "deleteExistingDocs": false,  
    "readme.copyFromDocs": false,  
  
    "markdown.preserveNewLines": true,  
    "markdown.prependGenNotice": true  
}

默认配置 / 文件结构

注意：说明已更新为使用非隐藏目录，但默认.json 文件仍然使用隐藏目录。这种不一致将在 v1.0 中得到解决。

config/scrawl.json：配置文件
docsrc/*.src.md：文档源文件（您的文档由此生成）
docs/：生成的文档输出
src/* 和 test/*：要扫描的代码文件
doctemplate/*.md.php 和 CodeScrawl/src/Template/*.md.php：可重用的模板
scrawl-bootstrap.php：在 $scrawl->run() 开始运行，$this 是 $scrawl 实例。

扩展

通过将它们的类名添加到您的 json 中的 'ScrawlExtensions' 配置中启用扩展。

可用扩展：（使用 \\ 使 json 愉快）

Tlf\\Scrawl\\Extension\\Notes：在代码中每次写入@NOTE some note text时，都会创建一个Notes.md文件，列出每次的笔记及其行号。如果笔记前面包含非注释字符，则会跳过这些笔记。示例 Notes.md
Tlf\\Scrawl\\TestExtension：仅用于调试目的

用法

概述

从项目根目录执行vendor/bin/scrawl
编写文件，例如docsrc/README.src.md
使用Markdown动词（mdverb）将文档和代码加载到.src.md文件中：@‌file(src/defaults.json)会打印出src/defaults.json的内容
使用@‌template mdverb加载模板：@‌template(php/compose_install, taeluf/code-scrawl)以打印composer安装说明
使用@‌ast mdverb从AST（非对称语法树）中加载代码：@‌ast(class.\Tlf\Scrawl.docblock.description)可以直接打印或@‌ast(class.\Tlf\Scrawl, ast/class)使用ast模板。
在代码源文件的注释中编写特殊的@‌codeverbs，以导出docblocks和代码。
扩展它！编写自定义模板和@‌mdverb处理器
编写自定义md动词处理器（见下文“扩展”部分）
编写自定义模板（见下文“扩展”部分）
在@符号之后使用一个ASCII Non-Joiner字符，以写入一个字面的@‌at_sign_with_text而不是执行动词处理器。

编写文档：示例

在docsrc文件夹中编写扩展名为.src.md的文件。
示例，来自docsrc/README.src.md

这将显示上面的## Install说明和## Configure说明

# Code Scrawl  
Intro text  
  
## Setup   
### Install  
@‌template(php/compose_install, taeluf/code-scrawl)  
  
### Configure  
Create a file `.config/scrawl.json` or `scrawl.json` in your project root. Defaults:

@‌file(src/defaults.json)
‌`

  
### `@‌MdVerbs` List  
Write these in your markdown source files for special functionality    
- `@import()`: Import something previously exported with `@export` or `@export_start/@export_end`. Usage: `@import(Namespace.Key)`    
- `@file()`: Copy a file's content into your markdown.. Usage: `@file(rel/path/to/file.ext)`    
- `@template()`: Load a template. Usage: `@template(template_name, arg1, arg2)`    
- `@link()`: Output links configured in your config json file.  
Config format is `{..., "links": { "link_name": "https://example.org"} }`. Usage: `@link(phpunit)`    
- `@easy_link()`: Get a link to common services (twitter, gitlab, github, facebook). Usage: `@easy_link(twitter, TaelufDev)`    
- `@hard_link()`: just returns a regular markdown link. In future, may check validity of link or do some kind of logging. Usage: `@hard_link(https://url.com, LinkName)`    
- `@see_file()`: Get a link to a file in your repo. Usage: `@see_file(relative/file/path)`    
- `@see()`: Get a link to a file in your repo. Usage: `@see_file(relative/file/path)`    
- `@system()`: Run a command on the computer's operating system.  
  
Supported options: `trim`, `trim_empty_lines`, `last_x_lines, int`    
- `@ast()`: Get an ast & optionally load a custom template for it. Usage: `@ast(class.ClassName.methods.docblock.description, ast/default)`    
  
  
### Template List  
Templates can be loaded with `@‌template(template_name, arg1, arg2)`, except `ast/*` templates (see below for those).  
  
Each template contains documentation for how to use it & what args it requres.  
  
  
### `@‌ast()` Templates (Asymmetric Syntax Tree)  
Example: `@‌ast(class.\Tlf\Scrawl.docblock.description)` to print directly or `@‌ast(class.\Tlf\Scrawl, ast/class)` to use an ast template.  
  
### `@‌CodeVerbs` Exports (from code in scan dirs)  
In a docblock, write `@‌export(Some.Key)` to export everything above it.  
  
In a block of code (or literally anywhere), write `// @‌export_start(Some.Key)` then `// @‌export_end(Some.Key)` to export everything in between.  
  
See [test/run/SrcCode.php](/test/run/SrcCode.php) for examples  
  
#### AST Templates Available  
- ast/ApiReadme  
- ast/class  
- ast/class_methodss  
- ast/debug  
- ast/default  
- ast/function_list  
- ast/method  
  
## Generate Changelog  
The template will print your git log.   
  
(*You may alternatively use the `@‌system()` verb at your own risk. I don't remember exactly how it handles different arguments, so it might be funky idk.*)

变更日志

已记录的变更（可能是高亮显示）

2024-08-20：在README顶部添加“文档”索引。添加了此变更日志示例

Git日志

@template(git/ChangeLog)

  
## Extensions  
  
### Templates: Write a custom template  
Look at existing templates in [doctemplate/](/doctemplate/) or [src/Template](/src/Template) for examples.  
  
### Verb Handlers: Write a custom verb handler  
In your `scrawl-bootstrap.php` file, do something like:

<?php
/**

@param $scrawl \Tlf\Scrawl实例
*/

$scrawl->verb_handlers['own_verb'] =

function($arg1, $arg2){  
    return $arg1.'--'.$arg2;  

};

  
### PHP Extensions  
Create a class that `implements \Tlf\Scrawl\Extension`. See file [src/Extension.php](/src/Extension.php). You can `class YourExt extends \Tlf\Scrawl\DoNothingExtension` as a base class and then only override the methods you need.  
  
In your `config.json`, set `"ScrawlExtensions": ["Your\\Fully\\Qualified\\ClassName"]`, with as many extension classes as you like.  
  
## Architecture  
- `Tlf\Scrawl`: Primary class that `run()`s everything.  
- `\Tlf\Scrawl->run()`: generate `api/*` files. Load all php classes. scan code files. Scan `.src.md` files & output `.md` files.  
    - file set as `file.bootstrap` is `require()`d at start of `run()` to setup additional mdverb handlers and (eventually) other extensions. Default is `scrawl-bootstrap.php`  
- `Tlf\Scrawl\Ext\MdVerbs`: Instantiated during `run()` prior to scanning documentation source files. When an `@‌mdverb(arg1,arg2)` is encounter in documentation source file, a handler (`$mdverbs->handlers['mdverb']`) is called with string arguments like `$handler('arg1', 'arg2')`. Extend it by adding a callable to `$scrawl->mdverb_ext->handlers`.  
    - `Tlf\Scrawl\Ext\MdVerb\MainVerbs`: Has functions for simple verb handlers like `@‌file`, `@‌template`. Adds each function as a handler to the `MdVerbs` class.  
    - `\Tlf\Scrawl\Ext\MdVerb\Ast`: A special mdverb handler that loads ASTs from the lexer and passes it to a named (or default) template.  
- `Tlf\Scrawl\FileExt\Php`: The only AST extension currently active. It is a convenience class that wraps the Lexer so it is easily called by `Scrawl`. It is called to setup ASTs by `class.ClassName...` on `$scrawl`. Call `$scrawl->get('ast', 'class.ClassName...')`. It is called to generate the `api/*` documentation files.  
- INACTIVE CLASS `Tlf\Scrawl\Ext\Main` simply copies the `project_root/.docrsc/README.src.md` to `project_root/README.md`  
- `Tlf\Scrawl\FileExt\ExportDocBlock` and `ExportStartEnd` handle the `@‌export()` tag in docblocks and the `@‌export_start()/@‌export_end()` tags.  
- `\Tlf\Scrawl\Utility\DocBlock`: Convenience class for extracting docblocks from files.  
- `\Tlf\Scrawl\Utility\Main`: Class with some convenience functions  
- `\Tlf\Scrawl\Utility\Regex`: Class to make regex matching within a file more abstract & object oriented. (it's not particularly good)  
  
## More Info  
- Run withOUT the cli: Some of the configs require absolute paths when running through php, rather than from the cli. An example is in [test/run/Integrate.php](/test/run/Integrate.php) under method `testRunFull()`  
- `@‌literal`: Displaying a literal `@‌literal` in an md source file can be done by putting a [Zero Width Non-Joiner](https://unicode-explorer.com/c/200C) after the arroba (`@`). You can also use a backslash like so: `@\literal`, but then the backslash prints  
- All classes in this repo: [docs/ClassList.md](/docs/ClassList.md)  
- `$scrawl` has a `get/set` feature. In a template, you can get an ast like `$scrawl->get('ast.Fully\Qualified\ClassName')`. Outside a template, you can use the `Php` class ([src/Ext/Php.php](/src/Ext/Php.php)) to get an ast from a file or string.  
- the `deleteExistingDocs` config has a bit of a sanity check to make sure you don't accidentally delete your whole system or something ...

taeluf / code-scrawl

维护者

详细信息