Taeluf.com

Sample of Code Scrawl features

This README file is generated by code scrawl from the source 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 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.

composer require taeluf/code-scrawl-example v0.5.x-dev   

or in your composer.json

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

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 .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 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 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 Taeluf.com. @‌hard_link(https://taeluf.com) renders as 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 .docsrc/README.src.md. It works for directories too.

Docblock Exports / imports

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

This is exported from a docblock  
  
@attr I think this tag is exported too  

Code Block Exports

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

function you_can_export_a_whole_block_of_code(){  
    echo "i could write real sample code, but why bother? lol";  
}  

Import whole file into MD

See src/ASmallFile.php

<?php echo "this is is is a small file."; ?>  

List of all exports

The WriteExportLists extension will create an exports/ directory that contains key files to list all exported ... stuff. See 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 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 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 # Key not found for 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.