This is still work in progress. The code already works (in a different context), but I'm new to the dependency publishing game. So I'm still trying to figure stuff out and had to publish it first, in order to test it.
This bundle auto-generates documentation from specific annotations.
The truth is in the code, sure, but the code is oftentimes spread out across many files and folders. One business logic feature can be based on various different areas in the code. This is especially problematic if code is used, which is difficult to trace, for example if a class, method or property is called dynamically and hence difficult to find via searching.
In these situations, the easiest way of understanding components is asking the architect to explain it. While doing so, they can just across different files and give brief comments on what happens where.
Documentation is work, usually associated with a context switch and oftentimes out of date. Also, without a good system, it's difficult to find the documentation for the area one is currently working on.
To solve these problems, this library uses annotations to auto-generate up-to-date documentation in an appealing format and present it all in one place. It is sourced from bits and pieces spread out across the code. The documentation happens where the code happens. This enables developers to let documentation become part of their coding work without switching context.
- Build for use in Symfony 5.2, compatibility with other software is uncertain.
- Requires that all analyzed PHP-files follow the PSR4 specification. Specifically, Specification 3.3 "The terminating class name corresponds to a file name ending in .php. The file name MUST match the case of the terminating class name." (See https://www.php-fig.org/psr/psr-4/#2-specification)
composer require steveolotu/featuredocu
// config/bundles.php
return [
//..
SteveOlotu\FeatureDocu\FeatureDocuBundle::class => ['all' => true],
];
To use the Twig template, the path needs to be registered first.
To do so, add the path to the file: config/packages/twig.yaml
.
If the variable "paths" doesn't exist yet, create it, but also add the default_path:
Before:
twig:
...
default_path: '%kernel.project_dir%/templates'
...
After:
twig:
...
default_path: '%kernel.project_dir%/templates'
paths:
- '%kernel.project_dir%/templates'
- '%kernel.project_dir%/vendor/steveolotu/featuredocu/templates'
...
Add one or more @FeatureDocuAnnotation
annotations to any class, method or property.
Required parameters are:
- identifier: The name of the feature. It is recommended to use slashes to separate levels.
- order: Order in which entries of one specific identifier will be displayed. Must be unique. Tipp: Using steps of 100 allows to add elements later on without having to update all respective references.
- Description: Text that explains which part of the feature this specific class, method or property has.
Examples:
@FeatureDocuAnnotation(identifier="Backup/generate", order="1000", description="UI starting point")
@FeatureDocuAnnotation(identifier="Backup/delete", order="1040", description="UI starting point.")
To generate output, three steps are required:
- Initialize Object with your desired path
$featureDocu = new FeatureDocu($path, $reader, $twig);
- Analyzing the output checks the files in the specified path
$featureDocu->analyze();
- Generate output.
- Array
$featureDocu->getOutputArray();
Html: A html table
$featureDocu->getOutputHtml();
Assume there are several references with the two identifiers backup/create
and backup/delete
.
- Array: List of features
The following code:
$featureDocu->getFeatureListNestedArray();
...will generate an array in the format:
['backup' => [
['create' => true],
['delete' => true],
]
Note: The value "true" is only a placeholder. The useful data is stored in the keys.
- Html: A hierarchically indented and numbered list
The following code:
$featureDocu->getFeatureListHtmlList();
...will generate a nested <ul>
-HTML list:
1 backup
1.1 create
1.2 delete
Note: The lowest level entries (those which represent actual identifiers, here: create
and backup
) are links to the sections in the HTML reference table (which needs to be on the same page in order for the connection to work).
- ListListObject: The internal object used to gather the information.
$featureDocu->getListObject();
- To get all class objects found in files, after analyzing the code, use:
$featureDocu->getClasses();
- Add some tests
- Requirements are uncertain, check
- Check code style
- Check for unused code
Special thanks to eFrane.