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

  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.