file gen-theme-setting-docs.php

Generates the markdown documentation for all available theme settings.

  1. #!/usr/bin/env php
  2. <?php
  3. /**
  4. * @file
  5. * Generates the markdown documentation for all available theme settings.
  6. */
  7. /**
  8. * Note: this script is intended to be executed independently via PHP, e.g.:
  9. * $ ./scripts/gen-theme-setting-docs.php
  10. */
  11. use Drupal\bootstrap\Bootstrap;
  12. use Drupal\bootstrap\Plugin\Setting\DeprecatedSettingInterface;
  13. use Drupal\bootstrap\Plugin\Setting\SettingInterface;
  14. use Drupal\Component\Render\FormattableMarkup;
  15. use Drupal\Component\Utility\Html;
  16. use Drupal\Core\Serialization\Yaml;
  17. $kernel = require_once __DIR__ . '/bootstrap.php';
  18. $bootstrap = Bootstrap::getTheme('bootstrap');
  19. /** @var \Drupal\bootstrap\Plugin\Setting\SettingInterface[] $settings */
  20. $settings = array_filter($bootstrap->getSettingPlugin(NULL, TRUE), function (SettingInterface $setting) {
  21. return !!$setting->getGroups();
  22. });
  23. // Populate the variables with settings.
  24. $variables = ['groups' => []];
  25. $deprecatedSettings = [];
  26. $replacementPairs = [
  27. '&quot;' => '"',
  28. '\n' => "\n",
  29. ];
  30. foreach ($settings as $id => $setting) {
  31. $defaultValue = $setting->getDefaultValue();
  32. $deprecated = FALSE;
  33. if ($setting instanceof DeprecatedSettingInterface) {
  34. $newSetting = $setting->getDeprecatedReplacementSetting()->getPluginId();
  35. $deprecated = [
  36. 'reason' => new FormattableMarkup($setting->getDeprecatedReason(), []),
  37. 'replacement' => new FormattableMarkup('<a href="#@anchor">@setting</a>', [
  38. '@anchor' => Html::cleanCssIdentifier($newSetting),
  39. '@setting' => $newSetting,
  40. ]),
  41. 'version' => new FormattableMarkup($setting->getDeprecatedVersion(), []),
  42. ];
  43. }
  44. $data = [
  45. 'id' => $id,
  46. 'description' => new FormattableMarkup(strtr($setting->getDescription(), $replacementPairs), []),
  47. 'defaultValue' => $defaultValue !== NULL ? new FormattableMarkup(strtr(trim(Yaml::encode([$id => $defaultValue])), $replacementPairs), []) : NULL,
  48. 'deprecated' => $deprecated,
  49. ];
  50. // Defer adding deprecated settings.
  51. if ($deprecated) {
  52. $deprecatedSettings[$id] = $data;
  53. }
  54. else {
  55. // Only get the first two groups (we don't need 3rd, or more, levels).
  56. $header = implode(' > ', array_slice(array_filter($setting->getGroups()), 0, 2, FALSE));
  57. $variables['groups'][$header][$id] = $data;
  58. }
  59. }
  60. // Add Deprecated settings last (special table).
  61. if ($deprecatedSettings) {
  62. $variables['deprecated'] = $deprecatedSettings;
  63. }
  64. $docsPath = "{$bootstrap->getPath()}/docs";
  65. // Render the settings.
  66. $output = Bootstrap::renderCustomTemplate("{$docsPath}/theme-settings.twig", $variables);
  67. // Save the generated output to the appropriate file.
  68. $result = Bootstrap::putContents("{$docsPath}/Theme-Settings.md", $output, '<!-- THEME SETTINGS GENERATION START -->', '<!-- THEME SETTINGS GENERATION END -->');
  69. if ($result) {
  70. echo 'Successfully generated theme documentation!';
  71. exit(0);
  72. }
  73. echo 'Unable to generate theme documentation!';
  74. exit(1);