Skip to content

A library for generating documentation files for your PHP code in GitHub compatible Markdown.

License

Notifications You must be signed in to change notification settings

xlientrc/xlient-doc-php

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Xlient PHP Markdown Documentation Generation Library

This library is a PHP documentor used to generate documentation files for your PHP code in GitHub compatible Markdown.

Requires PHP 8.1 or higher.

Install

composer require xlient/doc-php

Setup

Any php files you wish to generate documents for must be already loaded or autoloadable.

It is recommended to install them with composer and then point the srcDir parameter to your package folder in /vendor.

use Xlient\Doc\Php\Configuration;
use Xlient\Doc\Php\PhpDocumentor;

use const DIRECTORY_SEPARATOR as DS;

// Set current working directory to composer.json directory.
chdir(dirname(__DIR__));

// Include composer autoload file.
require_once getcwd() . DS . 'vendor' . DS . 'autoload.php';

// Configure the documentor.
$config = new Configuration(...);

// Instanciate the documentor.
$documentor = new PhpDocumentor(
    srcDirs: [
        getcwd() . '/vendor/package/name1/src',
        getcwd() . '/vendor/package/name2/src',
    ],
    destDir: getcwd() . '/docs',
    config: $config,
);

// Generate the documentation files.
$files = $documentor->make();

Configuration

All configuration is set using the Configuration class.

The parameter order of the Configuration class __construct method is not guaranteed to remain consistent between versions. For this reason it is recommended to use named parameters.

$config = new Configuration(
    baseNamespaces: [
        '\\Xlient'
    ],
    basePaths [
        '\\Xlient' => 'xlient'
    ],
    ...
);

baseNamespaces

Only files within these namespaces will be documented.

When creating directories, the equivalent directory path of this namespace will be trimmed from the start of the path.

Default

baseNamespace: [],

Example

baseNamespace: [
    '\\Xlient'
],

With baseNamespace: ['\\Xlient'], the resulting directory path of \\Xlient\\Doc\\Php will become /doc/php.

basePaths

These paths will be prepended to the start of any resulting relative documentation file path.

The array key is the namespace and the value the corresponding path.

Default

basePaths: [],

Example

basePaths: [
    '\\Xlient' => '/help'
],

With basePaths: ['\\Xlient' => '/help'], the resulting path of \\Xlient\\Doc\\Php\Configuration will become {destDir}/help/doc/php/configuration.md

baseUrls

This URL will be prepended to any URL paths generated for items that match a base namespace.

The array key is the namespace to match and the value the corresponding URL.

Default

baseUrls: [],

Example

baseUrls: [
    '\\Xlient' => 'https://xlient.com'
],

pathFixes

An array of key value pairs to override the default path name generation.

By default, namespaces will be broken up based on case. So MyName will become my-name.

This isn't always the desirable outcome, so this option allows you to modify the namespace value to an alternative.

Default

pathFixes: [],

Example

pathFixes: [
    'MyName' => 'myname'
],

namespaceUrls

An array of URLs to use for linking to items outside the base namespaces.

{php_doc} will get replaced with a php.net style document path.

With \\Random\\Engine\\Secure, the resulting filename will be class.random-engine-secure.php

Default

namespaceUrls: [
    '\\' => 'https://www.php.net/manual/en/{php_doc}',
    '\\Random\\' => 'https://www.php.net/manual/en/{php_doc}',
    '\\Psr\\' => 'https://www.php-fig.org',
    '\\Psr\\Cache\\' => 'https://www.php-fig.org/psr/psr-6',
    '\\Psr\\Clock\\' => 'https://www.php-fig.org/psr/psr-20',
    '\\Psr\\Container\\' => 'https://www.php-fig.org/psr/psr-11',
    '\\Psr\\EventDispatcher\\' => 'https://www.php-fig.org/psr/psr-14',
    '\\Psr\\Http\\Client\\' => 'https://www.php-fig.org/psr/psr-18',
    '\\Psr\\Http\\Message\\RequestFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\ResponseFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\ServerRequestFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\StreamFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\UploadedFileFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\UriFactoryInterface' => 'https://www.php-fig.org/psr/psr-17',
    '\\Psr\\Http\\Message\\' => 'https://www.php-fig.org/psr/psr-7',
    '\\Psr\\Http\\Server\\' => 'https://www.php-fig.org/psr/psr-15',
    '\\Psr\\Link\\' => 'https://www.php-fig.org/psr/psr-13',
    '\\Psr\\Log\\' => 'https://www.php-fig.org/psr/psr-3',
    '\\Psr\\SimpleCache\\' => 'https://www.php-fig.org/psr/psr-16',
],

Any namespaceUrls set in the configuration will be merged with the default.

urlCallback

A more precise method of providing external URLs.

Default

urlCallback: null,

Example

$url will contain the any matching namespaceUrls value or null if no matches.

urlCallback: function(string $name, ?string $url): ?string {
    if (str_starts_with($name, '\\Psr\\')) {
        $url = 'https://www.php-fig.org';
    }

    return $url;
},

methodUrlCallback

A method of providing external URLs for external class methods.

Default

methodUrlCallback: null,

Example

methodUrlCallback: function(string $class, string $method): ?string {
    $url = null;
    // ...
    return $url;
},

classPublic

When true, public class items will be included.

Default

classPublic: true,

classProtected

When true protected class items will be included.

Default

classProtected: true,

classPrivate

When true private class items will be included.

Default

classPrivate: true,

classSeparator

A string value to use to separate class names in the inheritance list.

Default

classSeparator: ' » ',

methodFiles

When true, separate files will be generated for each class method.

Default

methodFiles: true,

functionFiles

When true, separate files will be generated for each function.

functionFiles: true,

functionDir

When true, function files will be placed in a sub directory with the same name as the functions file.

functionDir: true,

classFilenamePrefix

A value to prepend to a class documentation filename.

Default

classFilenamePrefix: '',

Example

classFilenamePrefix: 'class-',

classFilenameSuffix

A value to append to a class documentation filename.

Default

classFilenameSuffix : '',

enumFilenamePrefix

A value to prepend to an enum documentation filename.

Default

enumFilenamePrefix : '',

enumFilenameSuffix

A value to append to an enum documentation filename.

Default

enumFilenameSuffix : '',

interfaceFilenamePrefix

A value to prepend to an interface documentation filename.

Default

interfaceFilenamePrefix : '',

interfaceFilenameSuffix

A value to append to an interface documentation filename.

Default

interfaceFilenameSuffix : '',

traitFilenamePrefix

A value to prepend to a trait documentation filename.

Default

traitFilenamePrefix : '',

traitFilenameSuffix

A value to append to a trait documentation filename.

Default

traitFilenameSuffix : '',

methodFilenamePrefix

A value to prepend to a method documentation filename.

Default

methodFilenamePrefix : '',

methodFilenameSuffix

A value to append to a method documentation filename.

Default

methodFilenameSuffix : '',

functionFilenamePrefix

A value to prepend to a function documentation filename.

Default

functionFilenamePrefix : '',

functionFilenameSuffix

A value to append to a function documentation filename.

Default

functionFilenameSuffix : '',

constantsFilename

The filename to use for a constants documentation file.

Default

constantsFilename : 'constants',

functionsFilename

The filename to use for a functions documentation file.

Default

functionsFilename : 'functions',

classPathPrefix

A value to prepend to a class documentation dirname.

Default

classPathPrefix: '',

Example

classPathPrefix: 'class-',

classPathSuffix

A value to append to a class documentation dirname.

Default

classPathSuffix : '',

enumPathPrefix

A value to prepend to an enum documentation dirname.

Default

enumPathPrefix : '',

enumPathSuffix

A value to append to an enum documentation dirname.

Default

enumPathSuffix : '',

interfacePathPrefix

A value to prepend to an interface documentation dirname.

Default

interfacePathPrefix : '',

interfacePathSuffix

A value to append to an interface documentation dirname.

Default

interfacePathSuffix : '',

traitPathPrefix

A value to prepend to a trait documentation dirname.

Default

traitPathPrefix : '',

traitPathSuffix

A value to append to a trait documentation dirname.

Default

traitPathSuffix : '',

labels

An array of key value pairs to use for documentation labels.

Default

labels: [
    'class' => 'Class',
    'extends' => 'Extends',
    'implements' => 'Implements',
    'uses' => 'Uses',
    'class_synopsis' => 'Class Synopsis',
    'constructor' => 'Constructor',
    'cases' => 'Cases',
    'case_details' => 'Case Details',
    'constants' => 'Constants',
    'constant_synopsis' => 'Constant Synopsis',
    'constant_details' => 'Constant Details',
    'properties' => 'Properties',
    'property_details' => 'Property Details',
    'methods' => 'Methods',
    'method_details' => 'Method Details',
    'functions' => 'Functions',
    'function_synopsis' => 'Function Synopsis',
    'function_details' => 'Function Details',
    'public' => 'Public',
    'protected' => 'Protected',
    'private' => 'Private',
    'name' => 'Name',
    'value' => 'Value',
    'type' => 'Type',
    'description' => 'Description',
    'returns' => 'Returns',
    'throws' => 'Throws',
    'deprecated' => 'Deprecated',
    'internal' => 'Internal',
    'generated' => 'Generated',
],

Any labels set in the configuration will be merged with the default.

makeClassDescription

When true, the class documentation will include a description of the class.

Default

makeClassDescription: true,

makeClassExtends

When true, the class documentation will include a list of parent classes.

Default

makeClassExtends: true,

makeClassImplements

When true, the class documentation will include a list of implemented interfaces.

Default

makeClassImplements: true,

makeClassUses

When true, the class documentation will include a list of traits used by the class.

Default

makeClassUses: true,

makeClassConstructor

When true, the class constructor will have its own section in the documentation file.

Default

makeClassConstructor: true,

makeClassSynopsis

When true, a php.net style class index will be generated.

Default

makeClassSynopsis: true,

makeClassCases

When true, any case statements in an enum will be documented.

Default

makeClassCases: true,

makeClassCaseDetails

When true, a more detailed overview of each case in an enum will be documented.

Default

makeClassCaseDetails: true,

makeClassConstants

When true, any constants in a class will be documented.

Default

makeClassConstants: true,

makeClassConstantDetails

When true, a more detailed overview of each constant in a class will be documented.

Default

makeClassConstantDetails: true,

makeClassProperties

When true, any properties in a class will be documented.

Default

makeClassProperties: true,

makeClassPropertyDetails

When true, a more detailed overview of each property in a class will be documented.

Default

makeClassPropertyDetails: true,

makeClassMethods

When true, any methods in a class will be documented.

Default

makeClassMethods: true,

makeClassMethodDetails

When true, a more detailed overview of each method in a class will be documented.

Default

makeClassMethodDetails: true,

makeConstants

When true, any constants that are direct children of a namespace will be documented.

Default

makeConstants: true,

makeConstantsDescription

When true, the constant documentation will include a description of each constant.

Default

makeConstantsDescription: true,

makeConstantSynopsis

When true, a PHP code synopsis of the constants will be generated.

Default

makeConstantSynopsis: true,

makeConstantDetails

When true, a more detailed overview of each constant will be documented.

Default

makeConstantDetails: true,

makeDefines

When true, constants defined with the define function will be included in the constant documentation.

Default

makeDefines: true,

makeFunctions

When true, any functions that are direct children of a namespace will be documented.

Default

makeFunctions: true,

makeFunctionsDescription

When true, the function documentation will include a description for each function.

Default

makeFunctionsDescription: true,

makeFunctionSynopsis

When true, a PHP code synopsis of the functions will be generated.

Default

makeFunctionSynopsis: true,

makeFunctionDetails

When true, a more detailed overview of each function will be documented.

Default

makeFunctionDetails: true,

makeSynopsisMeta

When true, a JSON meta file will be generated with snyopsis URL metadata to allow for injecting links after code highlighting.

Default

makeSynopsisMeta: true,

showDeprecated

When true, deprecated items will be included in the documentation.

Default

showDeprecated: true,

showDeprecatedLabel

When true, a deprecated label will appear under deprecated items in the documentation.

Default

showDeprecatedLabel: true,

showInternal

When true, internal items will be included in the documentation.

Default

showInternal: true,

showInternalLabel

When true, an internal label will appear under internal items in the documentation.

Default

showInternalLabel: true,

showGenerated

When true, generated items will be included in the documentation.

Default

showGenerated: true,

showGeneratedLabel

When true, a generated label will appear under generated items in the documentation.

Default

showGeneratedLabel: true,

accessModifierOrder

An array of PHP access modifiers in the order in which they are to appear in.

Default

use Xlient\Php\Doc\PhpAccessModifier;
//...
accessModifierOrder: [
    PhpAccessModifier::PUBLIC,
    PhpAccessModifier::PROTECTED,
    PhpAccessModifier::PRIVATE,
],

typeOrder

An array of PHP types in the order in which they are to appear in.

Default

use Xlient\Php\Doc\PhpType;
//...
typeOrder: [
    PhpType::NULL,
    PhpType::BOOL,
    PhpType::TRUE,
    PhpType::FALSE,
    PhpType::INT,
    PhpType::FLOAT,
    PhpType::STRING,
    PhpType::ARRAY,
    PhpType::ITERABLE,
    PhpType::CALLABLE,
    PhpType::OBJECT,
    PhpType::CLASS_NAME,
    PhpType::VOID,
    PhpType::SELF,
    PhpType::STATIC,
    PhpType::NEVER,
],

sortByName

When true, items will be sorted by name.

Default

sortByName: true,

sortByAccessModifier

When true, items will be sorted by the specified accessModifierOrder order.

Default

sortByAccessModifier: true,

groupByAccessModifier

When true, items will be grouped by access modifiers.

Default

groupByAccessModifier: true,

sortByType

When true, types will be sorted by the specified typeOrder order.

Default

sortByType: true,

inheritDocComments

When true, child class PHPDoc comments will inherit missing information from its corresponding parent PHPDoc comment.

@inheritDoc and {@inheritDoc} will also be handled accordingly.

@inheritdoc / @inheritDoc

Will inherit the entire parent PHPDoc comment.

{@inheritdoc} / {@inheritDoc}

Will only inherit the description and inline it in accordance with the standard.

If it is the only text / tag in the PHPDoc comment, it will instead inherit the entire parent PHPDoc comment. This is non-standard, but a lot of code uses {@inheritdoc} this way.

Default

inheritDocComments: true,

prioritizeDocComments

When true, the information contained in the PHPDoc comment will take precedence over the information gotten from reflection.

Default

prioritizeDocComments: true,

escapeDocComments

When true, PHPDoc comment text will be escaped to not interfere with Markdown.

Default

escapeDocComments = false,

useNullableSyntax

When true, ? will be used instead of null where appropriate.

Default

useNullableSyntax: true,

enableTables

When true, certain information will be placed in tables instead of a more mobile friendly headings and paragraphs.

Default

enableTables: true,

indentLength

The length in spaces to indent code by.

Default

indentLength: 4,

lineLength

The maximum length in characters a code line should be.

Default

lineLength: 80,

override

When true, any existing generated docs in the destDir will be removed before making.

Default

override = false,

About

A library for generating documentation files for your PHP code in GitHub compatible Markdown.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Languages