Sample of Code Scrawl features</h2> <p>This README file is generated by code scrawl from the source file @see_file(.docsrc/README.src.md). This repo intends to (but may fail to) demonstrate all the available features of Code Scrawl.</p> <p>After months of using Code Scrawl, I <strong>think</strong> (but don't know if) a thorough example is the best way to document it.</p> <p>Check out @easy_link(tlf, code-scrawl)</p> <h2>Play with it</h2> <p>You can install this repo with composer, then run <code>vendor/taeluf/code-scrawl/bin/scrawl</code> (from the root of the project dir) to re-build things. So you can just mess with stuff in the README.src.md file (link above) or make new <code>.src.md</code> files in <code>.docsrc</code> dir ... then run <code>scrawl</code> & just see what happens.</p> <p>@template(composer_install, taeluf/code-scrawl-example)</p> <h2>Terms</h2> <ul> <li> <code>md verbs</code> are things like <code>@‌import(A.Key)</code> that you write in a markdown source file to call an extension</li> <li> <code>markdown source file</code>: A markdown file that also contains Code Scrawl features</li> </ul> <h2>About this file</h2> <p>It seeks to demonstrate most of Code Scrawl's available, built-in features.</p> <p>See @see_file(.docsrc/README.src.md) for the source of this file & compare to this file's actual output.</p> <p>This file is copied from <code>.docsrc</code> via the <code>...\DefaultExt\CopyReadme</code> class in Code Scrawl.</p> <h2>Warnings</h2> <ul> <li>If you want <code>@‌import(A.Key)</code> literally written, in your docs, you need an @hard_link(https://unicode-explorer.com/c/200C,<code>ascii non-joiner</code>) after the <code>@</code> sign, so Code Scrawl doesn't parse it as an <code>md verb</code>.</li> <li>I don't remember the other warning I meant to write down</li> </ul> <h2>Templates</h2> <p>Templates are essentially view files that are written in PHP, output (usually) markdown, and are to be loaded directly into your documentation. Templates are included with <code>@‌template(templateName, ...argsForTemplate)</code>. The templates available are:</p> <ul> <li> <code>composer_install</code>: <code>@‌composer_install(vendor/package-name, ?version_number)</code>. version_number is optional & will be taken from the current branch name. The version is put out as <code>version_number.x-dev</code> so that won't work with all branch naming schemes</li> <li> <code>bash_install</code>: <code>@‌bash_install(command,rel/file/name)</code> ... it's not perfect</li> <li> <code>classList</code>: to write a whole document detailing a class ... can't trust the ast parser right now though</li> <li> <code>classMethods</code>: kinda same as classList, but it's just for showing methods</li> <li> <code>functionList</code>: kinda like class list but it just shows functions in a file</li> </ul> <h2>Extensions</h2> <h3>Simple MD Verbs</h3> <p>These are used inside your markdown files. I think the rest of the extensions are both more complex & deal with the source code. <code>MarkdownVerbs</code> class scans markdown source files to find verbs. Then it invokes <code>SimpleVerbs</code> to get replacements.</p> <ul> <li> <code>@‌import(A.Key)</code>: Import something directly into your markdown (see exports examples below)</li> <li> <code>@‌file(rel/path/to/file.ext)</code>: to copy the content of an entire file into your docs (example below)</li> <li> <code>@‌template(templateName, ...argsForTemplate)</code>: Load a template. The <code>...argsForTemplate</code> are comma-separated args defined by the given template</li> <li> <code>@‌easy_link(service, target)</code>: Example: <code>@‌easy_link(twitter, TaelufDev)</code> renders as @easy_link(twitter,TaelufDev) <ul> <li>supported services: <code>twitter</code>, <code>facebook</code>, <code>gitlab</code>, <code>github</code>, and <code>tlf</code> (tlf is for my personal url-shortening at <code>tluf.me</code> which is not available for public use. But you can link to my stuff). The others take your username.</li> </ul> </li> <li> <code>@‌hard_link(url, ?link_name)</code>: the link name is optional. Example: <code>@‌hard_link(https://taeluf.com, Taeluf.com)</code> renders as @hard_link(https://taeluf.com, Taeluf.com). <code>@‌hard_link(https://taeluf.com)</code> renders as @hard_link(https://taeluf.com)</li> <li> <code>@‌see_file(.docsrc/README.src.md)</code>: will render a markdown link to the file in your repo. This one will render as @see_file(.docsrc/README.src.md). It works for directories too.</li> </ul> <h3>Docblock Exports / imports</h3> <p>This text is copied from @see_file(src/DocblockExportsExample.php) where I'm using an <code>@export(Dumb.Docblock.ExampleExport)</code></p> <pre><code>@import(Dumb.Docblock.ExampleExport) </code></pre> <h3>Code Block Exports</h3> <p>This code is copied from @see_file(src/DocblockExportsExample.php) where I'm using <code>@export_start(Dumb.Codeblock.ExampleExport)</code> & <code>@export_end(Dumb.Codeblock.ExampleExport)</code></p> <pre><code class="language-php">@import(Dumb.Codeblock.ExampleExport) </code></pre> <h3>Import whole file into MD</h3> <p>See @see_file(src/ASmallFile.php)</p> <pre><code class="language-php">@file(src/ASmallFile.php) </code></pre> <h3>List of all exports</h3> <p>The <code>WriteExportLists</code> extension will create an <code>exports/</code> directory that contains key files to list all exported ... stuff. See @see_file(doc/exports/)</p> <h3>Code Scrawl Configs</h3> <p>I wrote a custom extension for Code Scrawl that (attempts to) export all the configs into documentation. I don't remember how well it works & it's literally just for Code Scrawl.</p> <h3>PHP Ast Parsing</h3> <p>The PHP Language extension will use my @easy_link(tlf, lexer) to create ASTs of all php files. The lexer is ... maybe not working well right now. The extension works, and the lexer captures some php language features but ... don't count on it.</p> <p>I don't know when I'll fix the lexer, but it's on my TODO list.</p> <h3>Bash Ast Parsing</h3> <p>v0.4 of Code Scrawl uses v0.2 of my @easy_link(tlf, lexer), which has an old implementation of getting very basic info from bash files. Don't count on it ...</p> <p>I don't know when I'll add bash to the current version of the lexer, but it's on my TODO list.</p> <h3>AST Imports</h3> <p><strong>NOTICE:</strong> This feature is ... unreliable but intended to be fixed & improved.</p> <p>Ast generation is in a very ... it's in a state of ... it exists kinda. See the notes on Php Ast & Bash Ast above. The gist is: <code>@‌ast(\Tlf\Scrawl\Ext\MdVerb\Ast, methods.getAstClassInfo.docblock)</code> would show the docblock content of the method <code>getAstClassInfo()</code> on the class <code>\Tlf\Scrawl\Ext\MdVerb\Ast</code>. WOULD show. Might show. Idunno. Fixing this up is on my TODO list. The available md verbs available with ASTs are:</p> <ul> <li> <code>@‌ast(className, methods.methodName)</code> or something like that</li> <li> <code>@‌classMethods()</code> ... I don't even know</li> <li> <code>@‌ast_class()</code>: Alias for <code>@‌ast()</code> ... i think? Idk</li> </ul> <h2>Errors</h2> <ul> <li>If you try to <code>@‌import(No)</code> but the key <code>No</code> does not exist, you'll see <code>@import(No)</code> & get a message in the CLI</li> </ul> <h2>Versioning of this repo</h2> <p>I intend to make the version number of this repo match the version number of code scrawl that it applies to.<

Sample of Code Scrawl features

This README file is generated by code scrawl from the source file @see_file(.docsrc/README.src.md). This repo intends to (but may fail to) demonstrate all the available features of Code Scrawl.

After months of using Code Scrawl, I think (but don't know if) a thorough example is the best way to document it.

Check out @easy_link(tlf, code-scrawl)

Play with it

You can install this repo with composer, then run vendor/taeluf/code-scrawl/bin/scrawl (from the root of the project dir) to re-build things. So you can just mess with stuff in the README.src.md file (link above) or make new .src.md files in .docsrc dir ... then run scrawl & just see what happens.

@template(composer_install, taeluf/code-scrawl-example)

Terms

md verbs are things like @‌import(A.Key) that you write in a markdown source file to call an extension
markdown source file: A markdown file that also contains Code Scrawl features

About this file

It seeks to demonstrate most of Code Scrawl's available, built-in features.

See @see_file(.docsrc/README.src.md) for the source of this file & compare to this file's actual output.

This file is copied from .docsrc via the ...\DefaultExt\CopyReadme class in Code Scrawl.

Warnings

If you want @‌import(A.Key) literally written, in your docs, you need an @hard_link(https://unicode-explorer.com/c/200C,ascii non-joiner) after the @ sign, so Code Scrawl doesn't parse it as an md verb.
I don't remember the other warning I meant to write down

Templates

Templates are essentially view files that are written in PHP, output (usually) markdown, and are to be loaded directly into your documentation. Templates are included with @‌template(templateName, ...argsForTemplate). The templates available are:

composer_install: @‌composer_install(vendor/package-name, ?version_number). version_number is optional & will be taken from the current branch name. The version is put out as version_number.x-dev so that won't work with all branch naming schemes
bash_install: @‌bash_install(command,rel/file/name) ... it's not perfect
classList: to write a whole document detailing a class ... can't trust the ast parser right now though
classMethods: kinda same as classList, but it's just for showing methods
functionList: kinda like class list but it just shows functions in a file

Extensions

Simple MD Verbs

These are used inside your markdown files. I think the rest of the extensions are both more complex & deal with the source code. MarkdownVerbs class scans markdown source files to find verbs. Then it invokes SimpleVerbs to get replacements.

@‌import(A.Key): Import something directly into your markdown (see exports examples below)
@‌file(rel/path/to/file.ext): to copy the content of an entire file into your docs (example below)
@‌template(templateName, ...argsForTemplate): Load a template. The ...argsForTemplate are comma-separated args defined by the given template
@‌easy_link(service, target): Example: @‌easy_link(twitter, TaelufDev) renders as @easy_link(twitter,TaelufDev)
- supported services: twitter, facebook, gitlab, github, and tlf (tlf is for my personal url-shortening at tluf.me which is not available for public use. But you can link to my stuff). The others take your username.
@‌hard_link(url, ?link_name): the link name is optional. Example: @‌hard_link(https://taeluf.com, Taeluf.com) renders as @hard_link(https://taeluf.com, Taeluf.com). @‌hard_link(https://taeluf.com) renders as @hard_link(https://taeluf.com)
@‌see_file(.docsrc/README.src.md): will render a markdown link to the file in your repo. This one will render as @see_file(.docsrc/README.src.md). It works for directories too.

Docblock Exports / imports

This text is copied from @see_file(src/DocblockExportsExample.php) where I'm using an @export(Dumb.Docblock.ExampleExport)

@import(Dumb.Docblock.ExampleExport)

Code Block Exports

This code is copied from @see_file(src/DocblockExportsExample.php) where I'm using @export_start(Dumb.Codeblock.ExampleExport) & @export_end(Dumb.Codeblock.ExampleExport)

@import(Dumb.Codeblock.ExampleExport)

Import whole file into MD

See @see_file(src/ASmallFile.php)

@file(src/ASmallFile.php)

List of all exports

The WriteExportLists extension will create an exports/ directory that contains key files to list all exported ... stuff. See @see_file(doc/exports/)

Code Scrawl Configs

I wrote a custom extension for Code Scrawl that (attempts to) export all the configs into documentation. I don't remember how well it works & it's literally just for Code Scrawl.

PHP Ast Parsing

The PHP Language extension will use my @easy_link(tlf, lexer) to create ASTs of all php files. The lexer is ... maybe not working well right now. The extension works, and the lexer captures some php language features but ... don't count on it.

I don't know when I'll fix the lexer, but it's on my TODO list.

Bash Ast Parsing

v0.4 of Code Scrawl uses v0.2 of my @easy_link(tlf, lexer), which has an old implementation of getting very basic info from bash files. Don't count on it ...

I don't know when I'll add bash to the current version of the lexer, but it's on my TODO list.

AST Imports

NOTICE: This feature is ... unreliable but intended to be fixed & improved.

Ast generation is in a very ... it's in a state of ... it exists kinda. See the notes on Php Ast & Bash Ast above. The gist is: @‌ast(\Tlf\Scrawl\Ext\MdVerb\Ast, methods.getAstClassInfo.docblock) would show the docblock content of the method getAstClassInfo() on the class \Tlf\Scrawl\Ext\MdVerb\Ast. WOULD show. Might show. Idunno. Fixing this up is on my TODO list. The available md verbs available with ASTs are:

@‌ast(className, methods.methodName) or something like that
@‌classMethods() ... I don't even know
@‌ast_class(): Alias for @‌ast() ... i think? Idk

Errors

If you try to @‌import(No) but the key No does not exist, you'll see @import(No) & get a message in the CLI

Versioning of this repo

I intend to make the version number of this repo match the version number of code scrawl that it applies to.