To be fair, the title of this tutorial is mildly misleading. Why? Because a template in phpDocumentor means so much more than just the look and feel of your generated documentation.
A template in phpDocumentor is a series of actions, called transformations, that is capable of crafting a desired output. With this mechanism it is possible to generate HTML, XML, PDF but also to copy files to a destination location or generate a report of errors found while scanning you project.
phpDocumentor has several different templates out-of-the-box to customize the look and feel of your documentation, and
more are released on a regular basis. With these templates it is also possible to generate your documentation, or parts
thereof, in different formats. An example of this is the
checkstyle template, with which you can generate an XML
file containing all documentation errors discovered by phpDocumentor in the checkstyle XML format.
To apply a template other than the default you can add the
$ phpdoc -d "./src" -t "./docs/api" --template="checkstyle"
With the above command phpDocumentor will no longer output HTML output but just the XML output containing all errors and warnings.
Sometimes you want to generate multiple formats at the same time; you could run phpDocumentor multiple times but it is more efficient to pass multiple templates. phpDocumentor will then optimize the generation of documentation and not re-run those steps that they have in common.
You can instruct phpDocumentor to use multiple templates by using a comma-separated list:
$ phpdoc -d "./src" -t "./docs/api" --template="checkstyle,clean"
Here you can see how both the
checkstyle template and the
clean template are applied; which results in both
HTML documentation and an XML Checkstyle error report.
When you have a company or project-branded template you can also use that with phpDocumentor by providing the location of your template’s folder:
$ phpdoc -d "./src" -t "./docs/api" --template="data/templates/my_template"
In the above example is demonstrated how a custom template in a folder
data/templates/my_template, relative to the
current working directory, is being used to generate documentation with.
In the chapters above we demonstrated how you can use a specific template using the command-line, but it is also possible to use a configuration file to describe which template should be used for your project.
This can be done by adding an element called
template to the element
transformation in the root of your XML
Here is an example where the clean and checkstyle templates are used:
<?xml version="1.0" encoding="utf-8" ?> <phpdocumentor> ... <transformations> <template name="clean"/> <template name="checkstyle"/> </transformations> </phpdocumentor>
It is also possible to create your own template using either XSL or Twig as templating engine. This can be done by extending, or re-using, parts of an existing template or by starting from scratch. phpDocumentor offers a lot of conveniences for template writers, which would go beyond the scope of this tutorial.
A tutorial for creating your own documentation with Twig is offered in the chapter Creating your own template using Twig, for a complete overview of all options and possibilities see the guide on creating templates how to accomplish this.
If you want to tweak one or two things it is also possible to define transformations directly in your configuration file. This way you can override the index, copy files (such as PDFs) or generate additional documents.
For example, here we see how a PDF (located at
data/specification.pdf of the template folder) is copied to the
destination location (the target folder) so that it may be referred to, and linked to, in the documentation.
<?xml version="1.0" encoding="utf-8" ?> <phpdocumentor> ... <transformations> <template name="clean"/> <transformation writer="FileIO" query="copy" source="data/specification.pdf" artifact="specification.pdf" /> </transformations> </phpdocumentor>