Various Yii 3.0 related documentation
Documentation is one of the most important parts of Yii.
Documentation for a package could either be in README.md or docs/{language}/{type} where {language} is
a language code and {type} could be “guide,” “cookbook” or something else.
Usually docs is there if the package usage or configuration isn’t trivial or there’s a need for translation.
Some indicators that it’s time to create docs:
If the total length of readme is less than about 200 lines, it’s fine to keep documentation in the readme.
The definitive guide, yiisoft/docs/guide aims at covering usage of packages as a whole framework. Unlike package documentation, it isn’t focused on a single package but is covering certain use-cases.
The guide should follow Micosoft style guide.
The definitive guide uses po4a in GitHub Action for translations.
Translation algorithm:
.po translation files. For example, Poedit, Lokalize,
Gtranslator or another._translations/guide/{lang}. Note that if the source file
is in a subfolder, the subfolder name is appended to the file name and separated by an underscore, for example,
for translating guide/en/concept/aliases.md file find _translations/guide/{lang}/concept_aliases.md.po file..po extension in Poedit from the folder with the desired localization,
for example _translations/guide/ru/intro_what-is-yii.md.po. If there is no localization yet,
create an issue.[!CAUTION] Do not change the translation in files in
/guide/{lang}manually.
If you have changed English and want to update translations:
Update docs translation in GitHub Action.po files by PoeditBlocks are in the GitHub Alerts format:
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
When translating documentation, these Block indicators should not be translated.
Keeps them intact as they are and only translate the block content.
For translating the label for the block, each guide translation should have a blocktypes.json file
containing the translations. The following shows an example for German:
{
"Note": "Hinweis",
"Tip": "Tipp",
"Important": "Wichtig",
"Warning": "Achtung",
"Caution": "Vorsicht"
}
PHPDoc mustn’t be added if it doesn’t add anything to what it describes. The following is a bad example:
use Psr\Log\LoggerInterface;
/**
* MyService class
*/
final class MyService extends MyServiceBase
{
/**
* @var LoggerInterface logger
*/
private LoggerInterface $logger;
/**
* MyService constructor.
* @param LoggerInterface $logger
*/
public function __construct(LoggerInterface $logger)
{
$this->logger = $logger;
}
/**
* @inheritDoc
*/
public function doit(): bool
{
return parent::doit();
}
}
PHPDoc, if present, should describe the purpose of the element it’s added for.
Each package readme should be placed into README.md and contain the following:
composer require.