rafie/gdoc

Documentation generator.

dev-master 2015-03-14 14:01 UTC

Requires

• php: >=5.3.3
• illuminate/container: 5.0.*
• illuminate/filesystem: 5.0.*
• illuminate/support: 5.0.*
• michelf/php-markdown: ~1.3
• symfony/console: ~2.1
• symfony/finder: ~2.1
• symfony/process: ~2.1
• symfony/yaml: ~2.1
• twig/twig: ~1.13

MIT

• RAFIE Younes

README

##Documentation Generator API documentation is important, but an official documentation for your application project is also important. I tried to adapt the Sami documentation generator to help generate official documentation.

##Installation You can require rafie/gdoc in your composer.jsonand do a composer update.

##Usage You can run the documentation generator from the command line.

$ php path/to/rafie.php generate your_config.php

Where the config file must return an instance of RAFIE\Configuration, you may use the config file inside the root of the package, this is an example.

use RAFIE\Configuration;
use Symfony\Component\Finder\Finder;

$dir = __DIR__ . '/doc';

$finder = Finder::create()->files()->in($dir);

$docConf = $dir.'/doc.yml';

$options = [
    'theme'       => 'laravel',
    'build_path'  => __DIR__ . '/build',
    'themesPaths' => [__DIR__ . '/src/themes/']
];

return new Configuration($finder, $docConf, $options);

You can use the Finder to lookup your markdown documentation. The $docConf can be used to describe your documentation navigation structure and it will parsed and passed to your theme file, for example, if you wanted to create the Laravel documentation structure.

navigation:
  Prologue:
    Releases Notes: releases.html
    Upgrade Guide: upgrade.html
    Contribution Guide: contributions.html
  Setup:
    Installation: installation.html
    Configuration: configuration.html
    ...

The options parameter specify three attributes, your theme name, themes paths (where you stored your themes), and the build path where you output the result.

##Using Git You can use versioned documentation by specifying a fourth option.

$dir = __DIR__ . '/doc';

$finder = Finder::create()->files()->in($dir);

$versions = RAFIE\Version\GitVersionCollection::create($dir)
    ->add('master', 'Master')
    ->add('4.2', '4.2');

$options = [
    'theme'       => 'laravel',
    'build_path'  => __DIR__ . '/build/%version%',
    'versions'    => $versions,
    'themesPaths' => [__DIR__ . '/src/themes/']
];

$docConf = $dir . '/doc.yml';

return new Configuration($finder, $docConf, $options);

The GitVersionCollection lets you specify which versions you want to use for the generation, and the result is passed as an option. Note that the build path contains a %version% which indicates the sub directory structure used for the output.

##Creating Themes You can this Github repository to learn more about theme.

##Demo The gDocDemo repository contain a demo for generating a documentation for Laravel framework, I'm using their CSS file and some of their HTML.