From 16f15ae2b2881c08e11ba09bb2d6ff06afb498af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ste=CC=81phane=20Goetz?= <stephane.goetz@onigoetz.ch>
Date: Tue, 21 Jul 2015 09:49:49 +0200
Subject: [PATCH] Add developer documentation

---
 daux/Processor.php                            | 10 +++
 docs/00_Getting_Started.md                    | 28 +++++-
 .../10_For_Developers/Creating_a_Processor.md | 89 +++++++++++++++++++
 3 files changed, 126 insertions(+), 1 deletion(-)
 create mode 100644 daux/Processor.php
 create mode 100644 docs/10_For_Developers/Creating_a_Processor.md

diff --git a/daux/Processor.php b/daux/Processor.php
new file mode 100644
index 0000000..da86f9c
--- /dev/null
+++ b/daux/Processor.php
@@ -0,0 +1,10 @@
+<?php namespace Todaymade\Daux\Extension;
+
+use Todaymade\Daux\Tree\Root;
+
+class Processor extends \Todaymade\Daux\Processor {
+
+    public function manipulateTree(Root $root)
+    {
+    }
+}
diff --git a/docs/00_Getting_Started.md b/docs/00_Getting_Started.md
index 9a6f162..7f8933e 100644
--- a/docs/00_Getting_Started.md
+++ b/docs/00_Getting_Started.md
@@ -36,7 +36,12 @@ Do you use Daux.io? Send me a pull request or open an [issue](https://github.com
 
 ## Download
 
-Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP 5.3 or greater. You can also run the documentation locally using Grunt.js, which is covered at the end of this readme.
+Download this repository as a zip, and unpack. Copy the files to a web server that can run PHP 5.3 or greater.
+You can also run the documentation locally using Grunt.js, which is covered at the end of this readme.
+
+If you don't intend to modify Daux.io and just want to use it, you only need to copy `resources`, `daux.phar`, `global.json`, `generate`, `serve` and `index.php` With these, you're ready to create your documentation.
+
+If however you wish to do some advanced modifications, I recommend you use the raw version and run `composer install` to get started.
 
 ## Generating a set of static files
 
@@ -233,6 +238,27 @@ Directory structure:
 │   │   │   ├── 05_Code_Highlighting.md
 ```
 
+### Format
+Change the output format. It is recommended you set only formats that support the live mode as this will also
+be read by the integrated web server. And you set the other formats (like confluence) only by command line
+
+```json
+{
+	"format": "html"
+}
+```
+
+### Processor
+You can set the processor in the documentation or as an option to the command line. If you need it when running the server, you should add it to the configuration.
+
+More information on how to create a Processor can be found [here](!For_Developers/Creating_a_Processor).
+ 
+```json
+{
+    "processor": "MyProcessor"
+}
+```
+
 ### HTML Export Configuration
 
 #### Themes
diff --git a/docs/10_For_Developers/Creating_a_Processor.md b/docs/10_For_Developers/Creating_a_Processor.md
new file mode 100644
index 0000000..60f6c9e
--- /dev/null
+++ b/docs/10_For_Developers/Creating_a_Processor.md
@@ -0,0 +1,89 @@
+The recommended way to extend Daux is through Processors.
+
+The main advantage, is that you can run it with the source or with `daux.phar` independently. You don't need to hack in the core.
+
+## Adding classes
+
+At the same level as your `daux.phar` file, you will see a `daux` directory, you can create all your classes here.
+
+The classes must respect the PSR-4 Naming convention. And have `\Todaymade\Daux\Extension` as a base namespace.
+ 
+By default, we created a `daux/Processor.php` file to get you started.
+
+## A quick test ?
+
+For the example we're just going to dump the tree and exit.
+
+```php
+    public function manipulateTree(Root $root)
+    {
+        print_r($root->dump());
+        exit;
+    }
+```
+
+also, add this at the beginning of the file:
+
+```php
+use Todaymade\Daux\Tree\Root;
+```
+
+Let's just try if it works by running `./generate --processor=Processor`
+
+Yes, you get a big array dump! You're good to go.
+
+## What can I achieve ?
+
+There are a few methods that you can override to add some
+
+### Change the parsed tree.
+
+By default, Daux.io parses your directory to find pages. but, for a reason or another, you might want to programmatically add some pages.
+
+This can be done with: 
+
+```php
+    public function manipulateTree(Root $root)
+    {
+    }
+```
+
+Two helpers from the class `Todaymade\Daux\Tree\Builder` will greatly help you doing that:
+
+```php
+    $new = Builder::getOrCreateDir($root, 'New Pages');
+
+    $page = Builder::getOrCreatePage($new, 'index');
+    $page->setContent('The index page for the new folder');
+
+    $page = Builder::getOrCreatePage($new, 'A New Hope');
+    $page->setContent('A long time ago in a galaxy far away');
+```
+
+Both methods `getOrCreateDir` and `getOrCreatePage` take two parameters : `parent` and `title`
+
+### Extend the Markdown Generator
+
+You can extend the Markdown Parser in any way wou want with this method.
+
+```php
+    public function extendCommonMarkEnvironment(Environment $environment)
+    {
+    }
+```
+
+See the details on [CommonMark's website](http://commonmark.thephpleague.com/customization/overview/).
+
+### Add new generators
+
+You can add new generators to Daux.io and use them right away, they must implement the 
+`\Todaymade\Daux\Format\Base\Generator` interface and if you want to use the live mode with your generator 
+you have to implement `\Todaymade\Daux\Format\Base\LiveGenerator`. 
+
+```php
+    public function addGenerators()
+    {
+        return ['custom_generator' => '\Todaymade\Daux\Extension\MyNewGenerator'];
+    }
+```
+