Taeluf.com

Code Scrawl

A documentation generation framework with some built-in extensions for exporting comments and code, and importing into markdown.

Status

Under development. The documentation is in bad shape. Today is April 1, 2021. Hoping this will be in great shape by the end of April.

Getting Started

1. Install

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

or in your composer.json

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

2. Usage

  1. Run scrawl init to create skeleton
  2. Review .docsrc/ dir & .config/scrawl.json & modify as you please
  3. git commit -am "initialize code scrawl" (optional)
  4. scrawl - to run scrawl & generate documentation
  5. git commit -am "Run code scrawl" (optional)

Overview

Structure (defaults)

  • .config/scrawl.json: configuration file
  • .docsrc/*.src.md: documentation source files
  • docs/: generated documentation output
  • README.md: copy of generated docs/README.md
  • src/*, code/*, and test/*: Files to process through lexer
  • .doctemplate/*.md.php and code-scrawl-dir/code/Template/*.md.php: re-usable templates

Features

Likely not all features are documented. Several are written in @see(code/Extension/MdVerb/SimpleVerbs.php).

  • Regex matching: See [test/input/Project/code/AbcExt.php](/test/input/Project/code/AbcExt.php) for an example
  • @‍template(template_name, arg1, arg2): Include a template, passing whatever args the template requires
  • @‍export(Some.Key): Export a docblock's text content
  • @‍export_start(Another.Key) & @‍export_end(Another.key): export all lines between these two
  • @‍import(Some.Key) or @‍import(Another.key) to import an exact copy of the exported content
  • @‍see_file(docs/Config.md) or @‍see_file(src/Something.php): Link to a file
  • @‍file(src/Something.php): Print full content of file
  • @‍hard_link(https://url.com, LinkName) Print a link
  • @‍easy_link(service, TaelufDev): Print link to https://service.tld/TaelufDev where service is one of: twitter, gitlab, github, facebook, tlf (my personal url shortener)

Templates

More

Now you have the basics. Please submit an issue to improve our docs if this intro has been insufficient.