# Code Scrawl
Documentation Generation with `@verbs()` in markdown for special functionality and templates for common documentation needs. Define your own verbs & templates.
Integrated with @easy_link(tlf, php/lexer) for ASTs of PHP classes (there may be bugs & it's tested only with php 7.4).
Run scrawl with `vendor/bin/scrawl` from your project root.
## Example `.docsrc/README.src.md`
See below for a list of templates & `@verbs` available to use.
This would display the `## Install` instructions and `## Configure` instructions as below
```md
# Code Scrawl
Intro text
## 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)
```
```
## Install
@template(php/composer_install, taeluf/code-scrawl)
## Configure
Create a file `.config/scrawl.json` or `scrawl.json` in your project root. Defaults:
```php
@file(src/defaults.json)
```
## Define your own verbs
In your `scrawl-bootstrap.php` file, do something like:
```php
@file(test/input/run-cli/scrawl-bootstrap.php)
```
## Write your own templates
Look at existing templates in @see_file(doctemplate/) or @see_file(src/Template) for examples.
## Run Scrawl
`cd` into your project root
```bash
# run documentation on the current dir
vendor/bin/scrawl
```
## File Structure (defaults)
- `.config/scrawl.json`: configuration file
- `.docsrc/*.src.md`: documentation source files (from which your documentation is generated)
- `docs/`: generated documentation output
- `code/*`, and `test/*`: Code files to scan
- `doctemplate/*.md.php` and `CodeScrawl/src/Template/*.md.php`: re-usable templates
- `scrawl-bootstrap.php`: Runs before `$scrawl->run()` and has access to `$scrawl` instance
## `@Verbs`
Write these in your markdown source files for special functionality
@template(Scrawl/MdVerbs)
## Templates
Templates can be loaded with `@template(template_name, arg1, arg2)`, though ast templates should be loaded with `@ast(class.ClassName.ast_path, ast/template_name)` where the template name is optional.
Click the link to view the template file to see the documentation on how to use it & what args it requires
@template(Scrawl/Templates)
## 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 @see_file(test/run/SrcCode.php) for examples
## 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 @see_file(test/run/Integrate.php) under method `testRunFull()`
- `@literal`: Displaying a literal `@literal` in an md source file can be done by putting a @hard_link(https://unicode-explorer.com/c/200C, Zero Width Non-Joiner) after the arroba (`@`). You can also use a backslash like so: `@\literal`, but then the backslash prints
- All classes in this repo: @see_file(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 (@see_file(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 ...