CODEWITHSUNDEEP
phpsymfonytwigphpdoc
altrugon
altrugon

Reputation: 311

Is it possible to use phpDocumentator on Twig templates?

I'm currently working on a Symphony project with Twig templates. In order to know what each template does I'm adding extensive comments on the files with descriptions, parameters, returns, etc...

I was hopping to be able to run phpDocumentator (or any other suitable tool) on these files and have an easily accessible documentation for all our developers, however every time I run the following command:

php phpDocumentor.phar -d src/dir1/dir2/CoreBundle/Resources/views/ -t docs/api/ -v

I get a nice Exception as result:

[Exception]
No parsable files were found, did you specify any using the -f or -d parameter?

I know the docBlock should looks like /** comment */ but comments on Twig looks like {# comment #}.

Is there a way/tool to be able to produce these documentation? If so, how do I do it?

Thanks

Upvotes: 2

Views: 1465

Answers (1)

lxg
lxg

Reputation: 13107

There is no “proper” way, but you could apply a pretty rotten hack:

  1. you copy files to a temporary location …
  2. … and replace the twig comments with PHP tags and comments.
  3. then you run phpDocumentor on those files.

Example:

#!/bin/bash

targetpath="/tmp/phpdoc"
[ -d "$targetpath" ] && rm -r $targetpath
mkdir -p $targetpath

for twigfile in $(find src/ -name '*.html.twig'); do
    newtwigfile="$targetpath/${twigfile//\//_}.php"
    perl -pe 's|{#|<?php /*|g' $twigfile | perl -pe 's|#}|*/ ?>|g' > $newtwigfile
done

php phpDocumentor.phar -d $targetpath -t docs/api/ -v

This may need some tweaking in regard to what phpDocumentor accepts as valid comment blocks.

Before:

<div>
    {#
        This is the glorious lorem ipsum.
    #}
    <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
    eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.</p>
</div>

After:

<div>
    <?php /*
        This is the glorious lorem ipsum.
    */ ?>
    <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
    eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.</p>
</div>

The downside of this, like of any hack, is that you need to know about this “processing” when you write your Twig comments.

Upvotes: 1

Related Questions