Add developer documentation

This commit is contained in:
Stéphane Goetz 2015-07-21 09:49:49 +02:00
parent 09252409b2
commit 16f15ae2b2
3 changed files with 126 additions and 1 deletions

10
daux/Processor.php Normal file
View File

@ -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)
{
}
}

View File

@ -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

View File

@ -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'];
}
```