taeluf/code-scrawl

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

0.8.1.1 2024-02-04 22:17 UTC

Requires

• taeluf/better-regex: v0.4.x-dev
• taeluf/cli: v0.1.x-dev
• taeluf/lexer: v0.8.x-dev

Requires (Dev)

• taeluf/tester: v0.3.x-dev

MIT

README

Code Scrawl

Code Scrawl generates documentation so your docs stay up-to-date with your code. It can run system commands, pull other files into your markdown, import code from your tests, and ensure links to other documentation files remain valid.

Extensions and reusable templates can be created by library developers to generate documentation, like the generation of Routes, Views, and Packages documentation in Liaison.

Docs

• Getting started (below)
• Configuration - How to configure Code Scrawl
• Markdown Verbs - @verb()s built into Code Scrawl
• Templates - Built-in templates & how to create your own
• AST Templates - Templates for printing PHP class and file information (& how to make your own)
• Extensions - Built-in Extensions & how to create your own

Getting Started

1. Install Code Scrawl: composer require taeluf/code-scrawl v0.8.x-dev --dev
2. Configure Code Scrawl (sample below, or see Configuration)
3. Create a .src.md file, and try some built-in md verbs. (see Markdown Verbs)
4. WARNING: Destination files will be overwritten... Run Code Scrawl: vendor/bin/scrawl

2. Configure Code Scrawl

These are the default configurations, which you can copy+paste into config/scrawl.json (or .config/scrawl.json). You will probably want to change "warning.deleteExistingDocs": false and "warning.overwriteRootREADME": false both to true, but be sure to commit or backup your old docs first so you don't lose your work.

See Configuration for more information.

config/scrawl.json:

{  
  
    "--comments":{  
        "Documentation": "Visit https://www.taeluf.com/docs/Code%20Scrawl or https://gitlab.com/taeluf/php/CodeScrawl"  
    },  
  
    "warning.deleteExistingDocs": false,   
    "warning.overwriteRootREADME": false,   
  
    "markdown.fixNewLines": true,   
    "markdown.prependNOEDIT": true,   
  
    "file.bootstrap":"scrawl-bootstrap.php",   
  
    "dir.docs": "docs",   
    "dir.src": "docsrc",   
    "dir.templates": ["doctemplate"],   
    "dir.scan": ["src", "test"],   
  
    "api.output_dir": "api/",   
    "api.generate_readme": true,   
  
    "scrawl.extensions": [   
        "Tlf\\Scrawl\\Extension\\Notes"  
    ]  
  
}  

3. Create a .src.md file

In your configured dir.src directory, create a file with the .src.md extension.

This is the README.src.md file for Code Scrawl, for the page you're reading now:

See: Markdown Verbs, Templates, AST Templates

docsrc/README.src.md:

# Code Scrawl  
Code Scrawl generates documentation so your docs stay up-to-date with your code. It can run system commands, pull other files into your markdown, import code from your tests, and ensure links to other documentation files remain valid.  
  
Extensions and reusable templates can be created by library developers to generate documentation, like the generation of Routes, Views, and Packages documentation in [Liaison](https://taeluf.com/docs/Liaison/TestServer/).  
  
## Docs  
- Getting started (*below*)  
- @see(docs/Configuration.md, Configuration) - How to configure Code Scrawl  
- @see(docs/MarkdownVerbs.md, Markdown Verbs) - `@verb()`s built into Code Scrawl  
- @see(docs/Templates.md, Templates) - Built-in templates & how to create your own  
- @see(docs/ASTTemplates.md, AST Templates) - Templates for printing PHP class and file information (*& how to make your own*)  
- @see(docs/Extensions.md, Extensions) - Built-in Extensions & how to create your own  
  
## Getting Started  
1. Install Code Scrawl: @template(php/composer_install_inline,,,--dev)  
2. Configure Code Scrawl (*sample below, or see @see(docs/Configuration.md, Configuration)*)  
3. Create a `.src.md` file, and try some built-in md verbs. (*see @see(docs/MarkdownVerbs.md, Markdown Verbs)*)  
4. **WARNING:** Destination files will be overwritten... Run Code Scrawl: `vendor/bin/scrawl`  
  
### 2. Configure Code Scrawl  
These are the default configurations, which you can copy+paste into `config/scrawl.json` (*or `.config/scrawl.json`*). You will **probably** want to change `"warning.deleteExistingDocs": false` and `"warning.overwriteRootREADME": false` both to `true`, but be sure to commit or backup your old docs first so you don't lose your work.  
  
See @see(docs/Configuration.md, Configuration) for more information.  
  
`config/scrawl.json`:  
```  
@file(src/defaults.json)  
```  
  
### 3. Create a `.src.md` file  
In your configured `dir.src` directory, create a file with the `.src.md` extension.  
  
This is the @see(/docsrc/README.src.md, README.src.md) file for Code Scrawl, for the page you're reading now:  
  
See: @see_files(docs/MarkdownVerbs.md; Markdown Verbs, docs/Templates.md; Templates, docs/ASTTemplates.md; AST Templates)  
  
`docsrc/README.src.md`:   
```md  
@system(bin/get_readme_src)  
```  
  
**Note:** I use a workaround in [bin/get_readme_src](/bin/get_readme_src) so that the `README.src.md`'s contents do not break the code block.  
  
**Note2:** I'm using @\see(bin/get_readme_src) in the first note ... and it is being rendered in the code block, and I don't know why.  
  

Note: I use a workaround in bin/get_readme_src so that the README.src.md's contents do not break the code block.

Note2: I'm using @\see(bin/get_readme_src) in the first note ... and it is being rendered in the code block, and I don't know why.