README.md 12 KB

Sami Markdown Extension

Table of content

  1. Markdown
    1. SamiTwigExtension An extension than builds a single ReadMe markdownfile out of your code.

Documentation

Markdown

Classes

SamiTwigExtension Markdown

An extension than builds a single ReadMe markdown file out of your code.

By now, most is done "behind the scene" and the template is very minimal. This means that it's not much you can do to change any of the layout etc, without editing the actual code/class, but you may want to change template structure by calling the methods "render_classes", "render_class" etc, but be aware that these methods does not remove whitespaces and takes care of any format issues your template will get.

This is in lack of a a single-file-documentation, for a project, and since the markdown language is very strict on format - (indentation, signs etc.) - using the twig template was a hassle, whitout ending with several "twig-files" that was unreadable (no indentation etc).

Get Sami and fork this repo

git clone giaever@git.giaever.org:joachimmg/sami-markdown.git

Include the SamiTwigExtension.php into your Sami configuration-file and add it to twig. See example.conf.php or

  • set template: "template" => "markdown"
  • add extension:
$sami["twig"]->addExtension(new Markdown\SamiTwigExtension());

Methods

Name Return Access Description
__construct public
getFunctions public Set the functions available for the template engine.
short_description string v null public static Returns the short description of a reflection.
long_description string v null public static Returns a long description (both short and long) of a reflection.
deprecated string v null public static Returnes a deprecated label if class, method etc is.
todo array v null public static Returns todo-tag for Reflection.
see array v null public static Returns see-tag for Reflection.
href string public static Returnes a markdown link.
toc string public static Tabel of contents
param_hint string public static Get hints of a param.
param_default string v null public static Get default for parameter.
method_hint string public static Get the methods hints.
method_access string public static Get access to method.
method_signature string public static Get signature of a method.
method_source_url string public static Return a link to method in source code.
render_methods string v null public static Render methods.
render_class string public static Render class
render_classes string v null public static Render one or more classes.
render_namespace string public static Render namespace.
render string public static Render the whole ReadMe.

Method details

__construct Markdown\SamiTwigExtension
public function __construct(bool $pretty_print = false);

Parameters

Type Variable Description
bool $pretty_print None

getFunctions Markdown\SamiTwigExtension
public function getFunctions();

Set the functions available for the template engine.


short_description Markdown\SamiTwigExtension
public static function short_description(Reflection $refl, bool $oneliner = true, int $max = -1);

Returns the short description of a reflection.

Parameters

Type Variable Description
Reflection $refl Reflection to return description of
bool $oneliner Removes every newline and tabulation.
int $max Maximum of letters

Returns: string v null


long_description Markdown\SamiTwigExtension
public static function long_description(Reflection $refl, bool $oneliner = false);

Returns a long description (both short and long) of a reflection.

Parameters

Type Variable Description
Reflection $refl Reflection to return description of
bool $oneliner Removes every newline and tabulation

Returns: string v null


deprecated Markdown\SamiTwigExtension
public static function deprecated(Reflection $refl, bool $notice = true);

Returnes a deprecated label if class, method etc is.

If $notice is false, it will include the deprecated note - if given in the documentation.

Parameters

Type Variable Description
Reflection $refl Reflection
bool $notice Just as notice

Returns: string v null


todo Markdown\SamiTwigExtension
public static function todo(Reflection $refl);

Returns todo-tag for Reflection.

Parameters

Type Variable Description
Reflection $refl Reflection to get todo tag from.

Returns: array v null


see Markdown\SamiTwigExtension
public static function see(Reflection $refl);

Returns see-tag for Reflection.

Parameters

Type Variable Description
Reflection $refl Reflection to get see-tag from.

Returns: array v null


href Markdown\SamiTwigExtension
public static function href(string $ltxt, string $lurl, bool $namespace = false, string $desc = null);

Returnes a markdown link.

To match the markdown template classes is linked to by #classname-namespace, and methods #method-namespace\classname and namespaces is linked to by #namespace, $namespace must be set to true when linking to it.

Parameters

Type Variable Description
string $ltxt The link text
string $lurl The link destination
bool $namespace True when linking to a namespace
string $desc Link title (like the html title/hover-tag)

Returns: string


toc Markdown\SamiTwigExtension
public static function toc(array $tree, int $depth);

Tabel of contents

Generates a table of contentes out of the whole project tree.

Parameters

Type Variable Description
array $tree The tree array passed from twig
int $depth depth Initially this should be 0

Returns: string


param_hint Markdown\SamiTwigExtension
public static function param_hint(ParameterReflection $param, bool $link = false);

Get hints of a param.

This could be string, bool etc or several if an parameter can be mixed. If it's not stated in the functions signature, the hint will automatically be mixed.

If the hint is a part of this package (root namespace), and link is set to true it will return an internal link to the type, but if link is set to true and the type is

it will either return a link to this type or add a Google search query-link.

Parameters

Type Variable Description
ParameterReflection $param The parameter
bool $link Set to true to link

Returns: string


param_default Markdown\SamiTwigExtension
public static function param_default(ParameterReflection $param);

Get default for parameter.

Parameters

Type Variable Description
ParameterReflection $param None

Returns: string v null


method_hint Markdown\SamiTwigExtension
public static function method_hint(MethodReflection $method, bool $link = false);

Get the methods hints.

This hints is typically what a method returns, e.g string, bool etc.

Method works similar as param_hint.

Parameters

Type Variable Description
MethodReflection $method None
bool $link = false

Returns: string


method_access Markdown\SamiTwigExtension
public static function method_access(MethodReflection $method);

Get access to method.

Returns if a method is abstract, final, protected etc. Access to a method can be a mix and this method will include every.

Parameters

Type Variable Description
MethodReflection $method None

Returns: string


method_signature Markdown\SamiTwigExtension
public static function method_signature(MethodReflection $method, bool $incname = true);

Get signature of a method.

Returns the function name, parameters and access. It also includes default parameter values if $incname is set to true.

The format will be

access function name(paramterers [= "value"]);

Parameters

Type Variable Description
MethodReflection $method Method reflection
bool $incname Adds default parameter values on true

Returns: string


method_source_url Markdown\SamiTwigExtension
public static function method_source_url(MethodReflection $method);

Return a link to method in source code.

Parameters

Type Variable Description
MethodReflection $method MethodReflection $method Method reflection

Returns: string


render_methods Markdown\SamiTwigExtension
public static function render_methods(array $methods);

Render methods.

Returns a summary and detailed description of every method in the method array.

Parameters

Type Variable Description
array $methods None

Returns: string v null


render_class Markdown\SamiTwigExtension
public static function render_class(ClassReflection $class);

Render class

Returns information about a class including it's methods.

Parameters

Type Variable Description
ClassReflection $class Class reflection

Returns: string


render_classes Markdown\SamiTwigExtension
public static function render_classes(array $classes);

Render one or more classes.

Should typically be used for a single namespace at the time.

Determines which kind of class (e.g trait, interface etc) and returns them in the structure/order

Namespace

  • Normal classes,
  • Traits,
  • Interfaces,
  • Exceptions.

Parameters

Type Variable Description
array $classes Array with ClassReflection

Returns: string v null


render_namespace Markdown\SamiTwigExtension
public static function render_namespace(string $namespace, array $namespaces, array $classes);

Render namespace.

Returns information about the whole namespace, as long as it's sub-namespaces and classes is passed along to the method.

Parameters

Type Variable Description
string $namespace The name of the namespace
array $namespaces Array with names of sub-namespaces
array $classes Array with ClassReflections

Returns: string


render Markdown\SamiTwigExtension
public static function render(array $namespaces, array $classes);

Render the whole ReadMe.

Will bind classes and it's sub-namespaces and render namespace for namespace.

Parameters

Type Variable Description
array $namespaces Array with names of namespaces
array $classes Array with ClassReflections

Returns: string