Generate Documentation

Liaison uses a Code Scrawl extension to automatically generate documentation for Liaison apps and websites.

Docs

• Setup
• Sample Code Scrawl Config
• Sample Liaison Config

Setup

1. Install Code Scrawl: composer require taeluf/code-scrawl v0.8.x-dev --dev
2. Create a Scrawl config file at config/scrawl.json. (below)
3. Add the Liaison extension to the Scrawl config: "ScrawlExtensions":["Lia\\Ext\\Scrawl"].
4. Setup a Liaison config. (below)
5. Run Code Scrawl: vendor/bin/scrawl WARNING: The sample config will delete existing documentation in the output dir.

Sample Code Scrawl Config

See Code Scrawl Documentation for more information.

WARNING: The sample config will delete existing documentation in the output dir.

Note: Code Scrawl fails to generate ASTs for newer PHP features, so may fail in some cases.

.config/scrawl.json (Liaison's scrawl config):

{  
    "readme.copyFromDocs": true,  
    "dir.docs": "docs",  
    "dir.template": ".docsrc",  
    "dir.template_files": ".doctemplate",  
    "dir.scan": ["src", "test/run"],  
    "deleteExistingDocs": true,  
    "markdown.preserveNewLines": true,  
    "markdown.prependGenNotice": true,  
    "autoload": {  
        "classmap":["src"]  
    },  
    "noprompt":false,  
    "scrawl.ext": {  
    },  
    "file.code.ext": [".php"],  
    "file.template.ext": [".src.md"],  
  
    "ScrawlExtensions": [  
        "Lia\\Ext\\Scrawl",  
        "Tlf\\Scrawl\\Extension\\Notes"  
    ],  
    "Lia.init_script": ".config/init-liaison.php"  
}  

Sample Liaison Config

config/liaison.json (Liaison's ... liaison config):

{  
    "--comment": "File paths are relative to the current working directory. You should run Liaison's bin script from the root of your project folder.",  
  
    "deliver_script": "test/Server/deliver.php",  
    "liaison_variable_name": "lia",  
  
    "--comment2": "deliver_script is where you setup liaison. liaison_variable_name is the name of the variable containing the liaison instance.",  
  
    "error_page_file": "/test/Server/generic-error-page.html",  
    "error_page_route": "/generic-error/",  
  
    "--comment3": "error_page_file tells liaison where to output your error page. When you want to display your error page, you will 'require' this one file and 'exit'. 'error_page_route' is a route on your site that will display the generic page.",  
  
    "liaison_docs_dir": "TestServer",  
  
    "--comment4": "liaison_docs_dir is required if you use the CodeScrawl extension 'Lia\\Ext\\Scrawl' to generate documentation for your site or app. It must be a relative directory path inside your documentation output directory."  
}