Skip to content

Latest commit

 

History

History
225 lines (180 loc) · 8.86 KB

readme.md

File metadata and controls

225 lines (180 loc) · 8.86 KB

BumbleDocGen / Technical description of the project / Configuration files

Configuration

Documentation generator configuration can be stored in special files. They can be in different formats: yaml, json, php arrays, ini, xml

But it is not necessary to use files to store the configuration; you can also initialize the documentation generator instance by passing there an array of configuration parameters (see demo-5)

During the instance creation process, configuration data is loaded into Configuration class, and the code works directly with it.

Configuration file example

Let's look at an example of a real configuration in more detail:

 project_root: '%WORKING_DIR%'
 templates_dir: '%project_root%/selfdoc/templates'
 output_dir: "%project_root%/docs"
 cache_dir: '%project_root%/.bumbleDocGenCache'
 output_dir_base_url: "/docs"
 language_handlers:
   php:
     class: \BumbleDocGen\LanguageHandler\Php\PhpHandler
     settings:
       file_source_base_url: 'https://github.com/bumble-tech/bumble-doc-gen/blob/master'
       async_source_loading_enabled: true
 source_locators:
   - class: \BumbleDocGen\Core\Parser\SourceLocator\RecursiveDirectoriesSourceLocator
     arguments:
       directories:
         - "%project_root%/src"
         - "%project_root%/selfdoc"
 twig_filters:
   - class: \SelfDocConfig\Twig\CustomFilter\EvalString
 twig_functions:
   - class: \SelfDocConfig\Twig\CustomFunction\FindEntitiesClassesByCollectionClassName
   - class: \SelfDocConfig\Twig\CustomFunction\PrintClassCollectionAsGroupedTable
   - class: \SelfDocConfig\Twig\CustomFunction\GetConfigParametersDescription
 plugins:
   - class: \SelfDocConfig\Plugin\TwigFilterClassParser\TwigFilterClassParserPlugin
   - class: \SelfDocConfig\Plugin\TwigFunctionClassParser\TwigFunctionClassParserPlugin
   - class: \BumbleDocGen\Core\Plugin\CorePlugin\LastPageCommitter\LastPageCommitter

In this example, we see the real configuration of the self-documentation of this project.

Here is an example of loading this configuration in PHP code:

 // Single file
 $docGenerator = (new DocGeneratorFactory())->create('config.yaml');
 
 // Multiple files
 $docGenerator = (new DocGeneratorFactory())->create('config.yaml', 'config2.yaml', 'config3.xml');

Handling and inheritance of configuration files

The documentation generator can work with several configuration files at once. When processing configuration files, each subsequent file has a higher priority and overwrites the previously defined parameters, but if the parameter has not yet been defined before, it will be added.

Each default configuration file inherits the base configuration: BumbleDocGen/Core/Configuration/defaultConfiguration.yaml, but the parent configuration file can be changed using the parent_configuration parameter. The inheritance algorithm is as follows: scalar types can be overwritten by each subsequent configuration, while arrays are supplemented with new data instead of overwriting.

Configuration parameters

Key Type Default value Description
parent_configuration string|null NULL Path to parent configuration file
project_root string NULL Path to the directory of the documented project (or part of the project)
templates_dir string NULL Path to directory with documentation templates
output_dir string '%project_root%/docs' Path to the directory where the finished documentation will be generated
cache_dir string|null '%WORKING_DIR%/.bumbleDocGenCache' Path to the directory where the documentation generator cache will be saved
output_dir_base_url string '/docs' Basic part of url documentation. Used to form links in generated documents.
git_client_path string 'git' Path to git client
check_file_in_git_before_creating_doc bool true Checking if a document exists in GIT before creating a document
page_link_processor PageLinkProcessorInterface BasePageLinkProcessor Link handler class on documentation pages
language_handlers array<LanguageHandlerInterface> NULL List of programming language handlers
source_locators array<SourceLocatorInterface> NULL List of source locators
use_shared_cache bool true Enable cache usage of generated documents
twig_functions array<CustomFunctionInterface> Functions that can be used in document templates
twig_filters array<CustomFilterInterface> Filters that can be used in document templates
plugins array<PluginInterface>|null List of plugins
additional_console_commands array<Command> NULL Additional console commands
Last page committer: fshcherbanich <[email protected]>
Last modified date: Sat Oct 28 11:03:31 2023 +0300
Page content update date: Mon Nov 06 2023
Made with Bumble Documentation Generator