Taeluf.com

Code Scrawl

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

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.