Code Scrawl

Documentation Generation with @‌verbs() in markdown for special functionality and templates for common documentation needs. Define your own verbs & templates.

Integrated with 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

# 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(code/defaults.json)  
‌```  

Install

composer require taeluf/code-scrawl v0.7.x-dev   

or in your composer.json

{"require":{ "taeluf/code-scrawl": "v0.7.x-dev"}}  

Configure

Create a file .config/scrawl.json or scrawl.json in your project root. Defaults:

{  
  
    "template.dirs": [".doctemplate"],  
  
    "dir.docs": "docs",  
    "dir.src": ".docsrc",  
    "dir.scan": ["code", "test"],  
  
    "file.bootstrap":"scrawl-bootstrap.php",  
  
    "deleteExistingDocs": false,  
    "readme.copyFromDocs": false,  
  
    "markdown.preserveNewLines": true,  
    "markdown.prependGenNotice": true  
}  

Define your own verbs

In your scrawl-bootstrap.php file, do something like:

<?php  
/**  
 * @param $scrawl instance of `\Tlf\Scrawl`  
 */  
  
$scrawl->verb_handlers['own_verb'] =   
    function($arg1, $arg2){  
        return $arg1.'--'.$arg2;  
  
    };  

Write your own templates

Look at existing templates in .doctemplate/ or code/Template for examples.

Run Scrawl

cd into your project root

# 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/code/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

• @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)
• @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)
• @ast(): Get an ast & optionally load a custom template for it. Usage: @ast(class.ClassName.methods.docblock.description, ast/default)

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

• ast/class
• ast/class_methods
• ast/default
• ast/function_list
• ast/method
• bash/install
• php/composer_install
• all_classes

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 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 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 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
• $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 (code/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 ...