Taeluf.com

Code Scrawl

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

Note!

Not really ready to use.

Status

Library works pretty well, but isn't stable yet (some internals may change soon), and its poorly documented right now. I hope this will be fixed by the end of April 2021. Today is April 1, 2021.

Getting Started

1. Install

  1. Download: git clone https://gitlab.com/taeluf/php/CodeScrawl.git CodeScrawl (put this anywhere you like)
  2. Modify bashrc: echo "export PATH=\""$(pwd)/CodeScrawl/cli:\$PATH"\"" >> ~/.bashrc;
    • To manually edit: gedit ~/.bashrc, or xed ~/.bashrc, vim ~/.bashrc, nano ~/.bashrc
  3. Reload terminal: source ~/.bashrc

2. Simple Example

  1. Create some folders & files:
    • docs/ <- Output directory
    • docs-src/ <- Documenation template files
    • docs-src/Test.src.md <- A template file
    • src/SomeFile.php <- It doesn't have to be PHP.
  2. Add a docblock export to your code: 
    • /**   
* I am a docblock  
* @export(Docblock.Test)  
*/
      @TODO support alternative docblock syntax, such as ##\n#\n#
  3. Add a wrapped export to your code: 
    • // @export_start(WrappedCode.Test)  
echo "I am an echo";  
// @export_end(WrappedCode.Test)
      Also supports # @export_...
  4. Import into your docs. In docs-src/Test.src.md, write: 
    • # Example of Docblock Import:  
@import(Docblock.Test)  

# Example of Wrapped Import:  
This is a nice way to auto copy+paste production or test code into your markdown file.  
`‌`‌`php  
@import(WrappedCode.Test)  
`‌`‌`
  5. Run Code Scrawl. cd into your project directory, then execute scrawl.
  6. Review docs/Test.md. The @import(KEY) calls will be replaced

3. Doing More

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