Changing the Look and Feel

优质

小牛编辑

125浏览

2023-12-01

Overview

With this tutorial I want to show you how the look and feel of phpDocumentor can be changed using one of the existing templates or by selecting a custom-made template.

What is a template?

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.

When phpDocumentor2 was created templates were still called ‘themes’ because originally their focus was on displaying a different skin for the output. During alpha we had to rename them to templates as it matched the functionality much more.

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.

This is possible because a template is a collection of those transformations; that can combine the assets of a template and your project’s structure information into a set of documentation.

Selecting a template

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 --template option:

$ 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.

Using multiple templates at once

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.

Using a custom template

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.

Adding templates to configuration

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 document.

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>

Creating your own look and feel

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>