Configuration

d2r-conf.php

The run configuration file is set up as an array. You can find the d2r-conf.php in your doc_root folder after running quickstart. Keys in the array correspond to the names of enum cases in the UnitEnum RC.

Example d2r-conf.php:

<?php

return array(
    'application_root' => '/abs/path/to/project/src',
    'vendor_directory' => '/abs/path/to/project/src/Acme',
    'bootstrap_file' => '/abs/path/to/project/docs/bootstrap.php',
    'doc_root' => '/abs/path/to/project/docs',
    'api_directory' => '/abs/path/to/project/docs/api',
    'api_docs_title' => 'api-docs',
    'show_visibility' => ReflectionMethod::IS_PUBLIC | ReflectionMethod::IS_PROTECTED,
    'excludes' =>
        array(
           "Acme\package04",
           "Acme\package01\package02\NotInDocsClass.php"
        ),
    'log_level' => 200,
    'toctree_max_depth' => 0,
    'toctree_titles_only' => true,
    'show_class_contents' => true,
    'user_provided_links' =>
        array(
            "Psr\Container" => "https://www.php-fig.org/psr/psr-11/"
        ),
    'link_to_sources' => false,
    'link_to_search_engine' => true,
    'download_file_ext' =>
        array(
            '.txt',
            '.csv',
            '.js',
            '.sql',
        ),
    'show_datestamp' => true,
);

See RC for a detailed discussion of options.

d2r-order.php

d2r-order.php determines the layout of your PHPDoc comments in the final documentation. You can find the d2r-order.php in your doc_root folder after running quickstart. Keys in the array are names of tags and names of elements of a PhpDocComment.

Example d2r-order.php:

<?php

/**
 * Gives the order of elements in DocComments.
 */
return [
    "@api" => "",
    "@deprecated" => "warning",
    "@internal" => "danger",
    "@todo" => "admonition",
    "@generated" => "",
    "summary" => "",
    "description" => "",
    "@inheritdoc" => "admonition",
    "@since" => "",
    "unknown_tags" => "",
    "@uses" => "",
    "@link" => "",
    "@see" => "admonition see also",
    "@package" => "",
    "@version" => "",
    "@author" => "",
    "@copyright" => "",
    "@license" => "",
    "@method" => "",
    "@var" => "",
    "signature" => "",
    "@param" => "",
    "@return" => "",
    "@throws" => "",
];

As said before, the order of the elements in the final documentation is determined by the order in which they appear in d2r-order.php. Apart from all the tag names starting with @, there are 4 other keys in the above array: summary, description, unknown_tags and signature.

Element names

Here is a short description of what these element names signify.

  • summary

    First line of your PhpDocComment (up to the first dot . or empty line) and will be printed fat. In the above example it is not the first element. For instance the @deprecated tag is before it. It might be convenient for your readers to see that a method or class is deprecated before they start reading the complete description and at the end find the method or class is deprecated.

  • description

    Rest of your PhpDocComment including inline tags. (Inline tags are surrounded with curly braces: {@inheritdoc}).

  • unknown_tags

    Tag names found in your PhpDocComments that do not appear in the d2r-order.php. These tags are listed in the final documentation at the specified place. For instance in the above they are listed between the @since and the @uses tags.

    By the way, you can specify the order (and layout) of any tag by just incorporating them as key => value in d2r-order.php. Fi “@myTag” => “admonition very important!” will appear as such in the documentation.

  • signature

    Signature of member. This is a signature:

    public static abstract function enumForName(
      Parameter #0 [ <required> string $id ]
 ): ?UnitEnum

If you leave out any of the above element name keys, they wil not be printed in the final documentation. The value of element name keys is of no importance; they wil not influence their layout.

Tag names

Tag names in d2r-order.php do not only specify where they appear in the final documentation; the value given determines their layout.

An empty string signifies no special layout. “@param” => “”:

param string $line - line to format

Given one of the Specific Admonitions the tag will be rendered as such. “@deprecated” => “warning”:

Warning

@deprecated 1.0.1 Use alternative method

The special admonition directive with no further name specified will take the tag name as title. “@todo” => “admonition”:

@todo

Explain the function of this method

Given a title it will be rendered as shown below. Example: “@see” => “admonition see also”:

see also

rtd for a detailed explanation

d2r-styles.txt

d2r-styles.txt is placed in your doc_root folder after running quickstart. It contains some style elements used by doc2rst. You can alter them as you please.

  • .block

    style of the datetime stamp at the end of each page

  • .tag0

    style of inline tag names

  • .tag3 - tag12

    style of tags as they are displayed in groups. Determines the width of the column.