I hate reading documenation that has code errors and/or sample output that is incorrect. I tried something new with this project and wrote a quick parser that can lint sample source code or execute and inject the actual result into a generated doc.
Don't make changes to the
[a-z]+.html
files directly!!
Change the associated [a-z]+.src.html
and then use the generate.php
script to generate the new [a-z]+.html
file. It can be run at the command line using php generate.php
from the project root when in the gh-pages
branch. Maybe someday I'll extract this out to another project or at least run it with a post receive hook, but for now its just a local tool, deal with it.
The commands are quickly explained below. To see some examples you can view the raw docs/index.src.html
file in this repo.
The lint
command is meant for confirming the code is valid and will eval()
the code passed into the function. Assuming there were no errors, the executed source code will then be injected back into the text replacing out the {{::lint()}}
. When you look at the raw docs/index.src.html
you will see that the code can span several lines. Remember the code is executed in the context of the running script so any variables will be available for the rest of the file.
{{::lint($var = 'brian nesbitt';)}} => $var = 'brian nesbitt';
As mentioned the
$var
can later be echo'd and you would get 'brian nesbitt' as all of the source is executed in the same scope.
The exec
command begins by performing an eval()
on the code passed into the function. The executed source code will then be injected back into the text replacing out the {{varName::exec()}}
. This will also create a variable named varName_eval
that you can then place anywhere in the file and it will get replaced with the output of the eval()
. You can use any type of output (echo
, printf
, var_dump
etc) statement to return the result value as an output buffer is setup to capture the output.
{{exVarName::exec(echo $var;)}} => echo $var;
{{exVarName_eval}} => brian nesbitt // $var is still set from above
The pad()
is a special source modifier. This will pad the code block to the indicated number of characters using spaces. Its particularly handy for aligning //
comments when showing results.
{{exVarName1::exec(echo 12345;/*pad(20)*/)}} // {{exVarName1_eval}}
{{exVarName2::exec(echo 6;/*pad(20)*/)}} // {{exVarName2_eval}}
... would generate to:
echo 12345; // 12345
echo 6; // 6
Apart from the docs the typical steps can be used to contribute your own improvements.