dreitier/awesome-documentation-blade-directives

Make better developer documentations

dev-main 2021-04-09 16:38 UTC

Requires

• php: ^7.1.3|^8.0
• jfcherng/php-diff: ^6.10
• laravel/framework: ^5.7|^6.0|^7.0|^8.0
• scrivo/highlight.php: v9.18.1.6

MIT

• Christopher Klein

• markdown
• highlight
• highlightjs
• dreitier
• awesome-documentation-blade-directives

README

If you want to create awesome documentation for developers, this package is for you.

Installation

You can install the package via composer:

composer require dreitier/awesome-documentation-blade-directives

Usage

Highlighting source code

This package uses scrivo/highlight.php to create highlighted source code.

@highlightStyle

Creates a <link rel="stylsheet" /> with the given style and version if provided.

@highlightStyle("atelier-heath-dark" /* style, optional */, "9.12.0" /* version, optional */)

@highlight

Highlight a given source code file.

• $path can be something like 'view:$path_in_laravel_views_folder' or a custom prefixed path
• $language can be any supported language by highlight.js

@highlight('view:documentation/samples/flow.php' /* path */, 'php' /* language, optional */)

@beginHighlight / @endHighlight

Highlight inline source code

@beginHighlight('php' /* language, optional */)
$a = 1;
$b = 2;
echo "$a + $b = " . ($a + $b);
@endHighlight

Diffing files

This package uses jfcherng/php-diff to create diffs between two strings.

@differStyle

Create inline CSS style to apply for the diff result.

@differStyle

@diffEncodedJson

Renders a previously created JSON diff:

$jsonDiff = \Dreitier\Documentation\Blade\Facades\Differ::calculate('old', 'new', 'Json' /* default, optional */);

@diffEncodedJson($jsonDiff, $render = null, $rendererOptions = null, $mergeOptions = false)

@diffArray

Renders a previously created array diff:

@diffArray($diff, $render = null, $rendererOptions = null, $mergeOptions = false)

Create a diff

You can easily create a diff between two files by using the facade:

$encodedJson = \Dreitier\Documentation\Blade\Facades\Differ::calculateFiles('view:samples/v1.php', 'view:samples/v2.php', $renderer = 'Json', $differOptions = null, $mergeDifferOptions = false, $rendererOptions = null, $mergeRendererOptions = false)

As you can see, you can use the prefix format of the static content locator (see below) to easily reference files.

Configuration

Highlighting source code

Setting highlight.js options

You can configure the used highlight.js options by using the facade:

\Dreitier\Documentation\Blade\Facades\Highlighter::setHighlightJsVersion('9.12.1');
\Dreitier\Documentation\Blade\Facades\Highlighter::setHighlightJsStyle('atelier-heath-light');

Set default language

If you want to set another default language than PHP, you can use setDefaultLanguage:

\Dreitier\Documentation\Blade\Facades\Highlighter::setDefaultLanguage('java');

Diffing files

You can use the following methods to configure the default options of jfcherng/php-diff:

\Dreitier\Documentation\Blade\Facades\Differ::setDefaultRenderer($defaultRenderer);
\Dreitier\Documentation\Blade\Facades\Differ::setDefaultRendererOptions($defaultRendererOptions);
\Dreitier\Documentation\Blade\Facades\Differ::setDefaultDifferOptions($differOptions);
\Dreitier\Documentation\Blade\Facades\Differ::setDefaultCss($css);

Static content locator

Register a new static content locator

This one comes handy if you want to reference source code or samples from other places, like composer packages:

\Dreitier\Documentation\Blade\Facades\StaticContentLocator::register('my-composer-package', function($path) {
    return base_path('vendor/my-namespace/my-composer-package/samples') . '/' . $path;
});

@highlight('my-composer-package:subdir/sample_1.json', 'json')