diff --git a/API/danog/PhpDoc/PhpDocBuilder.md b/API/danog/PhpDoc/PhpDocBuilder.md index 1815613..8d22982 100644 --- a/API/danog/PhpDoc/PhpDocBuilder.md +++ b/API/danog/PhpDoc/PhpDocBuilder.md @@ -1,6 +1,6 @@ --- -title: danog\PhpDoc\PhpDocBuilder: PHP documentation builder. -description: +title: "danog\\PhpDoc\\PhpDocBuilder: PHP documentation builder." +description: "" --- # `danog\PhpDoc\PhpDocBuilder` @@ -14,8 +14,6 @@ PHP documentation builder. ---- -Generated by [danog/phpdoc](https://phpdoc.daniil.it). ## Method list: * `fromNamespace(string $namespace): self` * `setAuthors(\phpDocumentor\Reflection\DocBlock\Tags\Author[] $authors): self` @@ -25,6 +23,8 @@ Generated by [danog/phpdoc](https://phpdoc.daniil.it). * `setName(string $name): self` * `setDescription(string $description): self` * `setImage(string $image): self` +* `addFrontMatter(string $key, string $value): self` +* `addIndexFrontMatter(string $key, string $value): self` * `run(): self` ## Methods: @@ -117,9 +117,33 @@ Parameters: +### `addFrontMatter(string $key, string $value): self` + +Add Jekyll front matter. + + +Parameters: +* `$key`: `string` Key +* `$value`: `string` Value + + + +### `addIndexFrontMatter(string $key, string $value): self` + +Add Jekyll index front matter. + + +Parameters: +* `$key`: `string` Key +* `$value`: `string` Value + + + ### `run(): self` Run documentation builder. +--- +Generated by [danog/phpdoc](https://phpdoc.daniil.it) diff --git a/composer.json b/composer.json index f57a0cd..7f3e08f 100644 --- a/composer.json +++ b/composer.json @@ -4,22 +4,31 @@ "type": "project", "license": "AGPL-3.0-only", "homepage": "https://phpdoc.daniil.it", - "keywords": ["phpdoc", "markdown", "documentation", "psalm"], + "keywords": [ + "phpdoc", + "markdown", + "documentation", + "psalm" + ], "require": { - "php": ">=7.4.0", + "php": "^8.0", "danog/class-finder": "^0.4", "phpdocumentor/reflection-docblock": "^5.2", + "phpstan/phpdoc-parser": "^1.2", "symfony/yaml": "^6.0" }, "require-dev": { "vimeo/psalm": "dev-master", "amphp/php-cs-fixer-config": "dev-master", - "friendsofphp/php-cs-fixer": "^2" + "friendsofphp/php-cs-fixer": "^2", + "phabel/phabel": "^1" }, - "authors": [{ - "name": "Daniil Gentili", - "email": "daniil@daniil.it" - }], + "authors": [ + { + "name": "Daniil Gentili", + "email": "daniil@daniil.it" + } + ], "autoload": { "psr-4": { "danog\\PhpDoc\\": "src/" @@ -29,13 +38,24 @@ "bin/phpdoc" ], "scripts": { - "check": [ - "@cs", - "@test" + "build": [ + "@cs-fix", + "@phpdoc" ], "cs": "PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix -v --diff --dry-run", "cs-fix": "PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix -v --diff", "psalm": "psalm", - "docs": "php tools/build_docs.php" + "docs": "@phpdoc" + }, + "config": { + "allow-plugins": { + "composer/package-versions-deprecated": true, + "phabel/phabel": true + } + }, + "extra": { + "phabel": { + "revision": 0 + } } } diff --git a/src/PhpDoc/PhpDoc.php b/src/PhpDoc.php similarity index 89% rename from src/PhpDoc/PhpDoc.php rename to src/PhpDoc.php index 3e651a2..3bfbbbb 100644 --- a/src/PhpDoc/PhpDoc.php +++ b/src/PhpDoc.php @@ -16,9 +16,12 @@ * @link https://phpdoc.daniil.it PhpDoc documentation */ -namespace danog\PhpDoc\PhpDoc; +namespace danog\PhpDoc; use danog\ClassFinder\ClassFinder; +use danog\PhpDoc\PhpDoc\ClassDoc; +use danog\PhpDoc\PhpDoc\FunctionDoc; +use danog\PhpDoc\PhpDoc\GenericDoc; use phpDocumentor\Reflection\DocBlock\Tags\Author; use phpDocumentor\Reflection\DocBlockFactory; use ReflectionClass; @@ -68,9 +71,17 @@ class PhpDoc */ private string $description = 'PHPDOC documentation'; /** - * Project image. + * Project front matter. + * + * @var array */ - private string $image = ''; + private array $frontMatter = []; + /** + * Index front matter. + * + * @var array + */ + private array $indexFrontMatter = []; /** * Use map. * @@ -244,14 +255,16 @@ class PhpDoc $description = \explode("\n", $this->description); $description = $description[0] ?? ''; - $descriptionEscaped = Escaper::escapeWithDoubleQuotes($description); - $nameEscaped = Escaper::escapeWithDoubleQuotes($this->name); + $frontMatter = $this->getIndexFrontMatter( + [ + 'description' => $description, + 'title' => $this->name, + ] + ); - $image = $this->getImage(); $index = <<name` @@ -568,25 +581,62 @@ class PhpDoc } /** - * Get project image (front matter). + * Get front matter. + * + * @param array $init Initial front matter * * @return string */ - public function getImage(): string + public function getFrontMatter(array $init = []): string { - return $this->image ? "\nimage: ".$this->image : ''; + $result = ''; + foreach ($init + $this->frontMatter as $key => $value) { + $result .= "$key: ".Escaper::escapeWithDoubleQuotes($value)."\n"; + } + return $result; } /** - * Set project image. + * Get index front matter. * - * @param string $image Project image + * @param array $init Initial front matter + * + * @return string + */ + private function getIndexFrontMatter(array $init = []): string + { + $result = ''; + foreach ($init + $this->indexFrontMatter as $key => $value) { + $result .= "$key: ".Escaper::escapeWithDoubleQuotes($value)."\n"; + } + return $result; + } + + /** + * Add project front matter. + * + * @param string $key Key + * @param string $value Value * * @return self */ - public function setImage(string $image): self + public function addFrontMatter(string $key, string $value): self { - $this->image = $image; + $this->frontMatter[$key] = $value; + + return $this; + } + /** + * Add index front matter. + * + * @param string $key Key + * @param string $value Value + * + * @return self + */ + public function addIndexFrontMatter(string $key, string $value): self + { + $this->indexFrontMatter[$key] = $value; return $this; } diff --git a/src/PhpDoc/ClassDoc.php b/src/PhpDoc/ClassDoc.php index bfbe86e..4471f23 100644 --- a/src/PhpDoc/ClassDoc.php +++ b/src/PhpDoc/ClassDoc.php @@ -2,6 +2,7 @@ namespace danog\PhpDoc\PhpDoc; +use danog\PhpDoc\PhpDoc; use phpDocumentor\Reflection\DocBlock\Tags\Generic; use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag; use phpDocumentor\Reflection\DocBlock\Tags\Property; diff --git a/src/PhpDoc/FunctionDoc.php b/src/PhpDoc/FunctionDoc.php index 977db74..70a6284 100644 --- a/src/PhpDoc/FunctionDoc.php +++ b/src/PhpDoc/FunctionDoc.php @@ -2,6 +2,7 @@ namespace danog\PhpDoc\PhpDoc; +use danog\PhpDoc\PhpDoc; use ReflectionFunction; /** diff --git a/src/PhpDoc/GenericDoc.php b/src/PhpDoc/GenericDoc.php index e6b640e..8c8ddff 100644 --- a/src/PhpDoc/GenericDoc.php +++ b/src/PhpDoc/GenericDoc.php @@ -2,6 +2,7 @@ namespace danog\PhpDoc\PhpDoc; +use danog\PhpDoc\PhpDoc; use phpDocumentor\Reflection\DocBlock; use phpDocumentor\Reflection\DocBlock\Description; use phpDocumentor\Reflection\DocBlock\Tags\Author; @@ -13,7 +14,6 @@ use phpDocumentor\Reflection\DocBlock\Tags\See; use phpDocumentor\Reflection\Fqsen as ReflectionFqsen; use ReflectionClass; use ReflectionFunction; -use Symfony\Component\Yaml\Escaper; /** * Generic documentation builder. @@ -175,18 +175,19 @@ abstract class GenericDoc $authors .= "> Author: $author \n"; } $seeAlso = $this->seeAlso(); - $image = $this->builder->getImage(); + $frontMatter = $this->builder->getFrontMatter( + [ + 'title' => "{$this->name}: {$this->title}", + 'description' => $this->description + ] + ); $index = ''; $count = \count(\explode('\\', $this->resolvedClassName)) - 2; $index .= \str_repeat('../', $count); $index .= 'index.md'; - $titleEscaped = Escaper::escapeWithDoubleQuotes("{$this->name}: {$this->title}"); - $descriptionEscaped = Escaper::escapeWithDoubleQuotes($this->description); return <<name` [Back to index]($index) diff --git a/src/PhpDoc/MethodDoc.php b/src/PhpDoc/MethodDoc.php index e1c87f0..f9ae67c 100644 --- a/src/PhpDoc/MethodDoc.php +++ b/src/PhpDoc/MethodDoc.php @@ -2,6 +2,7 @@ namespace danog\PhpDoc\PhpDoc; +use danog\PhpDoc\PhpDoc; use phpDocumentor\Reflection\DocBlock\Description; use phpDocumentor\Reflection\DocBlock\Tags\Generic; use phpDocumentor\Reflection\DocBlock\Tags\Param; diff --git a/src/PhpDocBuilder.php b/src/PhpDocBuilder.php index 8a2036a..535781b 100644 --- a/src/PhpDocBuilder.php +++ b/src/PhpDocBuilder.php @@ -18,7 +18,6 @@ namespace danog\PhpDoc; -use danog\PhpDoc\PhpDoc\PhpDoc; use phpDocumentor\Reflection\DocBlock\Tags\Author; /** @@ -142,11 +141,38 @@ final class PhpDocBuilder */ public function setImage(string $image): self { - $this->doc->setImage($image); + $this->doc->addFrontMatter('image', $image); + $this->doc->addIndexFrontMatter('image', $image); return $this; } + /** + * Add Jekyll front matter. + * + * @param string $key Key + * @param string $value Value + * @return self + */ + public function addFrontMatter(string $key, string $value): self + { + $this->doc->addFrontMatter($key, $value); + + return $this; + } + /** + * Add Jekyll index front matter. + * + * @param string $key Key + * @param string $value Value + * @return self + */ + public function addIndexFrontMatter(string $key, string $value): self + { + $this->doc->addIndexFrontMatter($key, $value); + + return $this; + } /** * Run documentation builder. * diff --git a/src/index.md b/src/index.md new file mode 100644 index 0000000..e6b7874 --- /dev/null +++ b/src/index.md @@ -0,0 +1,19 @@ +--- +description: "Simple markdown PHPDOC documentation generator with psalm type annotation support." +title: "danog/phpdoc" + +--- +# `danog/phpdoc` + +Simple markdown PHPDOC documentation generator with psalm type annotation support. + + + + +## Classes +* [\danog\PhpDoc\PhpDocBuilder: PHP documentation builder.](danog/PhpDoc/PhpDocBuilder.md) + + + +--- +Generated by [danog/phpdoc](https://phpdoc.daniil.it). \ No newline at end of file