diff --git a/demo/demo1/templates/sectionWithSubsections/pageLinkingExample/index.md.twig b/demo/demo1/templates/sectionWithSubsections/pageLinkingExample/index.md.twig index b9bacff4..3f8d09a4 100644 --- a/demo/demo1/templates/sectionWithSubsections/pageLinkingExample/index.md.twig +++ b/demo/demo1/templates/sectionWithSubsections/pageLinkingExample/index.md.twig @@ -3,12 +3,9 @@ {{ "Page linking example" | textToHeading('H1') }} -1) InvalidArgumentException - create a reference by short class name - -2) Doctrine\Common\Annotations\AnnotationException - creating a reference by full class name - -3) Class map - create a link to another page - -4) /demo/demo1/docs/sectionWithSubsections/classListExample/index.md - creating a link by file path - -5) /demo/demo1/docs/sectionWithSubsections/classListExample/index2.md - non-exists link case +1) [a]InvalidArgumentException[/a] - create a reference by short class name +2) [a]Doctrine\Common\Annotations\AnnotationException[/a] - creating a reference by full class name +3) [a x-title='Custom title']Doctrine\Common\Annotations\AnnotationException[/a] - creating a reference by full class name with custom title +4) [a]Class map[/a] - create a link to another page +5) [a]/demo/demo1/docs/sectionWithSubsections/classListExample/index.md[/a] - creating a link by file path +6) [a]/demo/demo1/docs/sectionWithSubsections/classListExample/index2.md[/a] - non-exists link case diff --git a/selfdoc/Twig/CustomFunction/GetConfigParametersDescription.php b/selfdoc/Twig/CustomFunction/GetConfigParametersDescription.php index 58df212a..d1abaf4b 100644 --- a/selfdoc/Twig/CustomFunction/GetConfigParametersDescription.php +++ b/selfdoc/Twig/CustomFunction/GetConfigParametersDescription.php @@ -27,11 +27,13 @@ public function __invoke(RootEntityCollection $rootEntityCollection, string $con preg_match("/({$name}:)([^#]+)(#)(( ?\([^\\)]+\\))?)(.*)/", $configContent, $matches); if (is_array($defaultValue)) { if (is_associative_array($defaultValue)) { - $tmpDefaultValue = "{$defaultValue['class']}|short_form"; + $shortName = array_reverse(explode('\\', $defaultValue['class']))[0]; + $tmpDefaultValue = "[a x-title='{$shortName}']{$defaultValue['class']}[/a]"; } else { $tmpDefaultValue = "\n\n"; foreach ($defaultValue as $v) { - $tmpDefaultValue .= "- {$v['class']}|short_form\n\n"; + $shortName = array_reverse(explode('\\', $v['class']))[0]; + $tmpDefaultValue .= "- [a x-title='{$shortName}']{$v['class']}[/a]\n\n"; } } $defaultValue = $tmpDefaultValue; diff --git a/selfdoc/templates/README.md.twig b/selfdoc/templates/README.md.twig index 294139fa..f715be6f 100644 --- a/selfdoc/templates/README.md.twig +++ b/selfdoc/templates/README.md.twig @@ -13,14 +13,14 @@ Add the BumbleDocGen to the `composer.json` file of your project using the follo {{ "Detailed technical description" | textToHeading('H2') }} -💡 Please refer to the Technical description of the project for a detailed explanation of all the classes and methods used. +💡 Please refer to the [a x-title="Description of the technical part of the project"]Technical description of the project[/a] for a detailed explanation of all the classes and methods used. {{ "Core Features" | textToHeading('H2') }} -- 🔍 Parser: +- 🔍 [a x-title="Parsing"]Parser[/a]: BumbleDocGen scans your project by parsing PHP files, extracting comments, and providing detailed models of your code. -- ✍️ Renderer: +- ✍️ [a x-title="Rendering"]Renderer[/a]: BumbleDocGen generates markdown content using templates and fills them with data obtained from parsing your code. - 🧠 AI tools for documentation generation: @@ -30,9 +30,9 @@ Add the BumbleDocGen to the `composer.json` file of your project using the follo {{ "Entry points" | textToHeading('H3') }} -BumbleDocGen's interface consists of mainly two classes: DocGenerator and DocGeneratorFactory. +BumbleDocGen's interface consists of mainly two classes: [a]DocGenerator[/a] and [a]DocGeneratorFactory[/a]. -- DocGenerator provides main operations for generating the documents. +- [a]DocGenerator[/a] provides main operations for generating the documents. - `addMissingDocBlocks()`: This method creates missing docBlocks in your code. - `fillInReadmeMdTemplate()`: This method prepares the `README.md` file using a predefined template. @@ -40,7 +40,7 @@ BumbleDocGen's interface consists of mainly two classes: DocGenerator and - `generateProjectTemplatesStructure()`: This method creates a structure for project templates. - `parseAndGetRootEntityCollectionsGroup()`: This method parses your project's files and collects information for the documentation. -- DocGeneratorFactory provides a method for creating `DocGenerator` instance. +- [a]DocGeneratorFactory[/a] provides a method for creating `DocGenerator` instance. - `create(configurationFiles: string)`: This method creates a `DocGenerator` instance using provided configuration files. - `setCustomConfigurationParameters(customConfigurationParameters: array)`: This method sets custom configuration parameters for the `DocGenerator` creation. diff --git a/selfdoc/templates/tech/1.configuration/readme.md.twig b/selfdoc/templates/tech/1.configuration/readme.md.twig index ff35fe91..74618163 100644 --- a/selfdoc/templates/tech/1.configuration/readme.md.twig +++ b/selfdoc/templates/tech/1.configuration/readme.md.twig @@ -8,7 +8,7 @@ They can be in different formats: yaml, demo-5) -During the instance creation process, configuration data is loaded into Configuration class, and the code works directly with it. +During the instance creation process, configuration data is loaded into [a]Configuration[/a] class, and the code works directly with it. {{ "Configuration file example" | textToHeading('H2') }} diff --git a/selfdoc/templates/tech/2.parser/entity.md.twig b/selfdoc/templates/tech/2.parser/entity.md.twig index 178510c6..a992b09b 100644 --- a/selfdoc/templates/tech/2.parser/entity.md.twig +++ b/selfdoc/templates/tech/2.parser/entity.md.twig @@ -41,7 +41,7 @@ Entities are always handled through collections. Collections are the result of t To further facilitate the handling of these entities, we utilize entity collections. These collections not only group relevant entities together but also provide convenient methods for filtering and manipulating these entities. -The root collections (RootEntityCollection), which are directly accessible in your templates, are as follows: +The root collections ([a]RootEntityCollection[/a]), which are directly accessible in your templates, are as follows: @@ -66,7 +66,7 @@ The root collections (RootEntityCollection), which are directly accessibl {{ "Available entities" | textToHeading('H2') }} -Following is the list of available entities that are consistent with EntityInterface and can be created. +Following is the list of available entities that are consistent with [a]EntityInterface[/a] and can be created. These classes are a convenient wrapper for accessing data in templates:
diff --git a/selfdoc/templates/tech/2.parser/entityFilterCondition.md.twig b/selfdoc/templates/tech/2.parser/entityFilterCondition.md.twig index 414282da..61ebe320 100644 --- a/selfdoc/templates/tech/2.parser/entityFilterCondition.md.twig +++ b/selfdoc/templates/tech/2.parser/entityFilterCondition.md.twig @@ -9,7 +9,7 @@ These rules facilitate a strategic extraction of elements, such as classes, meth By implementing these filters, users are endowed with the capability to customize the documentation output, ensuring that it precisely aligns with their requirements and expectations. This level of granularity not only streamlines the documentation process but also guarantees that the resultant documents are devoid of superfluous details, focusing solely on pertinent information. -All filter conditions implement the ConditionInterface interface. +All filter conditions implement the [a]ConditionInterface[/a] interface. {{ "Mechanism for adding entities to the collection" | textToHeading('H2') }} diff --git a/selfdoc/templates/tech/2.parser/readme.md.twig b/selfdoc/templates/tech/2.parser/readme.md.twig index 341c1e1d..76ee1214 100644 --- a/selfdoc/templates/tech/2.parser/readme.md.twig +++ b/selfdoc/templates/tech/2.parser/readme.md.twig @@ -3,7 +3,7 @@ {{ "Documentation parser" | textToHeading('H1') }} -Most often, we need ProjectParser in order to get a list of entities for documentation. +Most often, we need [a]ProjectParser[/a] in order to get a list of entities for documentation. But this is not the only use of this tool. The result of the parser's work (a collection of entities) can be used to programmatically analyze the project and perform any operations based on this analysis. For example, in our documentation generator, we also use the result of the parser in the tasks of generating documentation using AI tools. You can also use the parser for your own purposes other than generating documentation. diff --git a/selfdoc/templates/tech/2.parser/sourceLocator.md.twig b/selfdoc/templates/tech/2.parser/sourceLocator.md.twig index 328d857d..0957a20e 100644 --- a/selfdoc/templates/tech/2.parser/sourceLocator.md.twig +++ b/selfdoc/templates/tech/2.parser/sourceLocator.md.twig @@ -15,7 +15,7 @@ Source locators are set in the configuration: - "%project_root%/src" - "%project_root%/selfdoc"' | textToCodeBlock('yaml') }} -You can create your own source locators or use any existing ones. All source locators must implement the SourceLocatorInterface interface. +You can create your own source locators or use any existing ones. All source locators must implement the [a]SourceLocatorInterface[/a] interface. {{ "Built-in source locators" | textToHeading('H2') }} diff --git a/selfdoc/templates/tech/3.renderer/02_breadcrumbs.md.twig b/selfdoc/templates/tech/3.renderer/02_breadcrumbs.md.twig index 5ad83b2a..d815b3a4 100644 --- a/selfdoc/templates/tech/3.renderer/02_breadcrumbs.md.twig +++ b/selfdoc/templates/tech/3.renderer/02_breadcrumbs.md.twig @@ -4,7 +4,7 @@ {{ "Documentation structure and breadcrumbs" | textToHeading('H1') }} -To work with breadcrumbs and get the structure of the documentation, we use the inner class BreadcrumbsHelper. +To work with breadcrumbs and get the structure of the documentation, we use the inner class [a]BreadcrumbsHelper[/a]. To build the documentation structure, twig templates from the `templates_dir` configuration are used. {{ "Project structure definitions" | textToHeading('H2') }} @@ -25,7 +25,7 @@ In this way, complex documentation structures can be created with less file nest {{ "Displaying breadcrumbs in documents" | textToHeading('H2') }} -There is a built-in function to generate breadcrumbs in templates GeneratePageBreadcrumbs. +There is a built-in function to generate breadcrumbs in templates [a]GeneratePageBreadcrumbs[/a]. Here is how it is used in twig templates: {{ '{{ generatePageBreadcrumbs(title, _self) }\}' | textToCodeBlock('twig') }} diff --git a/selfdoc/templates/tech/3.renderer/04_twigCustomFilters.md.twig b/selfdoc/templates/tech/3.renderer/04_twigCustomFilters.md.twig index 188f4b94..b01ab5df 100644 --- a/selfdoc/templates/tech/3.renderer/04_twigCustomFilters.md.twig +++ b/selfdoc/templates/tech/3.renderer/04_twigCustomFilters.md.twig @@ -30,7 +30,7 @@ twig_filters: ``` It is important to remember that when a template is inherited, custom filters are not overridden and augmented. -This information is detailed on page Configuration files. +This information is detailed on page [a]Configuration files[/a]. {{ "Defautl template filters" | textToHeading('H2') }} diff --git a/selfdoc/templates/tech/3.renderer/05_twigCustomFunctions.md.twig b/selfdoc/templates/tech/3.renderer/05_twigCustomFunctions.md.twig index aaf23456..e4807e11 100644 --- a/selfdoc/templates/tech/3.renderer/05_twigCustomFunctions.md.twig +++ b/selfdoc/templates/tech/3.renderer/05_twigCustomFunctions.md.twig @@ -10,7 +10,7 @@ Functions available during page generation are defined in Configuration files. +This information is detailed on page [a]Configuration files[/a]. {{ "Defautl template functions" | textToHeading('H2') }} diff --git a/selfdoc/templates/tech/3.renderer/templatesLinking.md.twig b/selfdoc/templates/tech/3.renderer/templatesLinking.md.twig index bf89dff1..3387e7fc 100644 --- a/selfdoc/templates/tech/3.renderer/templatesLinking.md.twig +++ b/selfdoc/templates/tech/3.renderer/templatesLinking.md.twig @@ -9,7 +9,7 @@ We have several options for this, such as using special functions or using a spe {{ "Completing blank links" | textToHeading('H2') }} -Plugin PageHtmlLinkerPlugin have been added to the basic configuration, +Plugin [a]PageHtmlLinkerPlugin[/a] have been added to the basic configuration, which process the text of the filled template before its result is written to a file, and fill in all empty links. For example, an empty link: @@ -24,5 +24,5 @@ will be replaced with this link: The second way to relink templates is to generate links through functions. -There are a number of functions that allow you to get a link to an entity, for example GetDocumentedEntityUrl, and there are also functions for getting a link to other documents, for example GetDocumentationPageUrl. +There are a number of functions that allow you to get a link to an entity, for example [a]GetDocumentedEntityUrl[/a], and there are also functions for getting a link to other documents, for example [a]GetDocumentationPageUrl[/a]. You can also implement your own functions for relinking if necessary. \ No newline at end of file diff --git a/selfdoc/templates/tech/3.renderer/templatesVariables.md.twig b/selfdoc/templates/tech/3.renderer/templatesVariables.md.twig index a42580a5..6094aa13 100644 --- a/selfdoc/templates/tech/3.renderer/templatesVariables.md.twig +++ b/selfdoc/templates/tech/3.renderer/templatesVariables.md.twig @@ -8,4 +8,4 @@ There are several variables available in each processed template. 1) Firstly, these are built-in twig variables, for example `_self`, which returns the path to the processed template. -2) Secondly, variables with collections of processed programming languages are available in the template (see LanguageHandlerInterface). For example, when processing a PHP project collection, a collection ClassEntityCollection will be available in the template under the name phpClassEntityCollection +2) Secondly, variables with collections of processed programming languages are available in the template (see [a]LanguageHandlerInterface[/a]). For example, when processing a PHP project collection, a collection [a]ClassEntityCollection[/a] will be available in the template under the name phpClassEntityCollection diff --git a/selfdoc/templates/tech/4.pluginSystem/readme.md.twig b/selfdoc/templates/tech/4.pluginSystem/readme.md.twig index 40436636..acce6f40 100644 --- a/selfdoc/templates/tech/4.pluginSystem/readme.md.twig +++ b/selfdoc/templates/tech/4.pluginSystem/readme.md.twig @@ -5,7 +5,7 @@ The documentation generator includes the ability to expand the functionality using plugins that allow you to add the necessary functionality to the system without changing its core. -The system is built on the basis of an event model, each plugin class must implement PluginInterface. +The system is built on the basis of an event model, each plugin class must implement [a]PluginInterface[/a]. {{ "Configuration example" | textToHeading('H2') }} @@ -45,7 +45,7 @@ Plugins for any programming languages work regardless of which language handler diff --git a/src/Core/Configuration/defaultConfiguration.yaml b/src/Core/Configuration/defaultConfiguration.yaml index aa05f546..37af6999 100644 --- a/src/Core/Configuration/defaultConfiguration.yaml +++ b/src/Core/Configuration/defaultConfiguration.yaml @@ -32,5 +32,6 @@ twig_filters: # (array) Filters that - class: \BumbleDocGen\Core\Renderer\Twig\Filter\PregMatch plugins: # (array|null) List of plugins - class: \BumbleDocGen\Core\Plugin\CorePlugin\PageLinker\PageHtmlLinkerPlugin + - class: \BumbleDocGen\Core\Plugin\CorePlugin\PageLinker\PageLinkerPlugin - class: \BumbleDocGen\Core\Plugin\CorePlugin\LastPageCommitter\LastPageCommitter additional_console_commands: # (array) Additional console commands diff --git a/src/Core/Plugin/CorePlugin/PageLinker/PageHtmlLinkerPlugin.php b/src/Core/Plugin/CorePlugin/PageLinker/PageHtmlLinkerPlugin.php index ede008c6..292db680 100644 --- a/src/Core/Plugin/CorePlugin/PageLinker/PageHtmlLinkerPlugin.php +++ b/src/Core/Plugin/CorePlugin/PageLinker/PageHtmlLinkerPlugin.php @@ -18,10 +18,10 @@ * Existent page name => Existent page name * * @example - * \Namespace\ClassName => Custom title + * \Namespace\ClassName => Custom title * * @example - * \Namespace\ClassName => \Namespace\ClassName + * \Namespace\ClassName => \Namespace\ClassName * * @example * Non-existent page name => Non-existent page name diff --git a/src/Core/Plugin/CorePlugin/PageLinker/PageLinkerPlugin.php b/src/Core/Plugin/CorePlugin/PageLinker/PageLinkerPlugin.php new file mode 100644 index 00000000..b2f36125 --- /dev/null +++ b/src/Core/Plugin/CorePlugin/PageLinker/PageLinkerPlugin.php @@ -0,0 +1,52 @@ + Existent page name + * + * @example + * [a x-title="Custom title"]\Namespace\ClassName[/a] => Custom title + * + * @example + * [a]\Namespace\ClassName[/a] => \Namespace\ClassName + * + * @example + * [a]Non-existent page name[/a] => Non-existent page name + */ +final class PageLinkerPlugin extends BasePageLinker +{ + protected function getLinkRegEx(): string + { + return '/(\\[a(?![^>]*\bhref\b)[^\\]]*\\])(.*?)(\\[\/a\\])/m'; + } + + protected function getUrlFromMatch(string $match): string + { + preg_match($this->getLinkRegEx(), $match, $m); + return $m[2] ?? '#'; + } + + protected function getCustomTitleFromMatch(string $match): string + { + preg_match('/(x-title=("|\')(.*?)("|\'))/', $match, $m); + return $m[3] ?? ''; + } + + protected function getOutputTemplate(): string + { + return '%title%'; + } +} diff --git a/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/classes.md.twig b/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/classes.md.twig index 5830ddec..2d5fcba1 100644 --- a/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/classes.md.twig +++ b/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/classes.md.twig @@ -8,10 +8,10 @@ {% for abstractClassEntity in phpClassEntityCollection.getOnlyAbstractClasses() %} - + {% endfor %} {% for classEntity in phpClassEntityCollection.getOnlyInstantiable() %} - + {% endfor %}
    {% for key in pluginEntity.getMethodEntity('getSubscribedEvents').getFirstReturnValue() | eval | keys %} -
  • {{ key }}|short_form
    • +
  • [a]{{ key }}|short_form[/a]
    • {% endfor %}
NameNamespace
Abstract classes
{{ abstractClassEntity.getName() }}|short_form{{ abstractClassEntity.getNamespaceName() }}
[a x-title='{{ classEntity.getShortName() }}']{{ abstractClassEntity.getName() }}[/a]{{ abstractClassEntity.getNamespaceName() }}
Classes
{{ classEntity.getName() }}|short_form{{ classEntity.getNamespaceName() }}
[a x-title='{{ classEntity.getShortName() }}']{{ classEntity.getName() }}[/a]{{ classEntity.getNamespaceName() }}
\ No newline at end of file diff --git a/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/interfaces.md.twig b/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/interfaces.md.twig index 38043d92..437bee78 100644 --- a/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/interfaces.md.twig +++ b/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/interfaces.md.twig @@ -7,6 +7,6 @@ {% for interfaceEntity in phpClassEntityCollection.getOnlyInterfaces() %} - + {% endfor %}
NameNamespace
{{ interfaceEntity.getName() }}|short_form{{ interfaceEntity.getNamespaceName() }}
[a x-title='{{ interfaceEntity.getShortName() }}']{{ interfaceEntity.getName() }}[/a]{{ interfaceEntity.getNamespaceName() }}
\ No newline at end of file diff --git a/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/traits.md.twig b/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/traits.md.twig index 265b90af..73428e7c 100644 --- a/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/traits.md.twig +++ b/src/LanguageHandler/Php/Plugin/CorePlugin/EntityDocUnifiedPlace/templates/__structure/traits.md.twig @@ -7,6 +7,6 @@ {% for traitEntity in phpClassEntityCollection.getOnlyTraits() %} - + {% endfor %}
NameNamespace
{{ traitEntity.getName() }}|short_form{{ traitEntity.getNamespaceName() }}
[a x-title='{{ traitEntity.getShortName() }}']{{ traitEntity.getName() }}[/a]{{ traitEntity.getNamespaceName() }}
\ No newline at end of file