From 643e8a68e0974da892bbef24543ae8a573e12c3e Mon Sep 17 00:00:00 2001 From: Moshe Weitzman Date: Fri, 24 Jul 2020 02:17:40 -0400 Subject: [PATCH] Add a new mk:docs command to auto-build an official Drush Commands web site (#4472) --- .github/workflows/commands.yml | 73 +++++++++ .gitignore | 2 + README.md | 7 +- composer.json | 3 +- docs/index.md | 28 +--- misc/favicon.ico | Bin 0 -> 1150 bytes src/Commands/core/MkCommands.php | 177 +++++++++++++++++++++ src/Commands/help/ListCommands.php | 2 +- src/Commands/pm/SecurityUpdateCommands.php | 2 +- sut/drush/Commands/FixtureCommands.php | 3 + 10 files changed, 264 insertions(+), 33 deletions(-) create mode 100644 .github/workflows/commands.yml mode change 100644 => 120000 docs/index.md create mode 100644 misc/favicon.ico create mode 100644 src/Commands/core/MkCommands.php diff --git a/.github/workflows/commands.yml b/.github/workflows/commands.yml new file mode 100644 index 0000000000..08c0263d07 --- /dev/null +++ b/.github/workflows/commands.yml @@ -0,0 +1,73 @@ +name: Build Commands Site + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the master branch +on: + push: + branches: [master] +# pull_request: +# branches: [master] + +jobs: + build: + name: Build and Deploy + runs-on: ubuntu-latest + steps: + - name: Checkout master + uses: actions/checkout@v2 + + - name: Checkout gh-pages branch + uses: actions/checkout@v2 + with: + ref: gh-pages + path: gh-pages + + - name: Set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: '3.8' + + - name: Install Python dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs + + - name: Setup PHP + uses: shivammathur/setup-php@v2 + with: + php-version: 7.3 + extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite + coverage: none + + - name: Install Composer dependencies + run: composer install --prefer-dist --no-interaction --no-suggest + + - name: Install Drupal + run: composer sut:si + env: + UNISH_DB_URL: sqlite://sites/default/files/.ht.sqlite + + - name: Drush status + run: ./drush --uri=dev st + + - name: Drush mk:docs + run: composer mk:docs + + - name: Mkdocs build + run: cd build-commands && mkdocs build -v --site-dir ../gh-pages/commands/10.x + + - name: Commit and Push to gh-pages + run: | + cd gh-pages + + git config --local user.email "actions@github.com" + git config --local user.name "GitHub Action" + + git add -A . + + if git diff-index --quiet HEAD --; then + echo "No changes..." + else + git commit -m "[CI] build commands static site" + git push + fi diff --git a/.gitignore b/.gitignore index ea3e34bc70..0dfcc3ff0c 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,8 @@ box.phar drush.phar #The mkdocs output directory. site +#The Commands site output directory. +build-commands #The sami output directories api .sami-cache diff --git a/README.md b/README.md index 657d5d3995..f0198221d2 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ -Drush is a command line shell and Unix scripting interface for Drupal. Drush core ships with lots of useful commands for interacting with code like modules/themes/profiles. Similarly, it runs update.php, executes SQL queries and DB migrations, and misc utilities like run cron or clear cache. Developers love the `generate` command, which jump starts your coding project by writing ready-to-customize PHP and YML files. Drush can be extended by [3rd party commandfiles](https://www.drupal.org/project/project_module?f[2]=im_vid_3%3A4654). +Drush is a command line shell and Unix scripting interface for Drupal. Drush core ships with lots of [useful commands](https://www.drush.org/commands/10.x/) for interacting with code like modules/themes/profiles. Similarly, it runs update.php, executes SQL queries and DB migrations, and misc utilities like run cron or clear cache. Developers love the `generate` command, which jump starts your coding project by writing ready-to-customize PHP and YML files. Drush can be extended by [3rd party commandfiles](https://www.drupal.org/project/project_module?f[2]=im_vid_3%3A4654). [![Latest Stable Version](https://poser.pugx.org/drush/drush/v/stable.png)](https://packagist.org/packages/drush/drush) [![Total Downloads](https://poser.pugx.org/drush/drush/downloads.png)](https://packagist.org/packages/drush/drush) [![License](https://poser.pugx.org/drush/drush/license.png)](https://packagist.org/packages/drush/drush) [![Documentation Status](https://readthedocs.org/projects/drush/badge/?version=master)](https://readthedocs.org/projects/drush/?badge=master) [![Twitter](https://img.shields.io/badge/Twitter-%40DrushCli-blue.svg)](https://twitter.com/intent/user?screen_name=DrushCli) Resources ----------- -* [Installing (and Upgrading)](http://docs.drush.org/en/master/install/) -* [General Documentation](http://docs.drush.org) +* [Installing (and Upgrading)](http://docs.drush.org/en/master/install/) ([Drush 8](https://docs.drush.org/en/8.x/install/)) +* [General Documentation](http://docs.drush.org) ([Drush 8](https://docs.drush.org/en/8.x/install/)) +* [Commands](https://www.drush.org/commands/10.x/) * [API Documentation](http://www.drush.org/api/master/index.html) * [Drush packages available via Composer](https://packagist.org/search/?type=drupal-drush) * [A list of modules that include Drush integration](https://www.drupal.org/project/project_module?f[2]=im_vid_3%3A4654&solrsort=ds_project_latest_release+desc) diff --git a/composer.json b/composer.json index c35972d014..ed683a71cd 100644 --- a/composer.json +++ b/composer.json @@ -98,8 +98,9 @@ ], "api": "PATH=$HOME/bin:$PATH sami.phar --ansi update sami-config.php", "sami-install": "mkdir -p $HOME/bin && curl --output $HOME/bin/sami.phar http://get.sensiolabs.org/sami.phar && chmod +x $HOME/bin/sami.phar", + "mk:docs": "./drush --uri=dev -v mk:docs --destination=../build-commands", "sut": "./drush --uri=dev", - "sut:si": "./drush site:install testing --uri=dev --sites-subdir=dev --db-url=${UNISH_DB_URL:-mysql://root:password@mariadb}/unish_dev -v", + "sut:si": "./drush --uri=dev site:install testing --sites-subdir=dev --db-url=${UNISH_DB_URL:-mysql://root:password@mariadb}/unish_dev -v", "phpunit": "php -d sendmail_path='true' vendor/bin/phpunit --colors=always --configuration tests", "unit": "composer phpunit -- --testsuite unit", "integration": "composer phpunit -- --testsuite integration", diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 000f196c2d..0000000000 --- a/docs/index.md +++ /dev/null @@ -1,27 +0,0 @@ -Drush is a command line shell and Unix scripting interface for Drupal. Drush core ships with lots of useful commands for interacting with code like modules/themes/profiles. Similarly, it runs update.php, executes sql queries and DB migrations, and misc utilities like run cron or clear cache. Drush can be extended by [3rd party commandfiles](https://www.drupal.org/project/project_module?f[2]=im_vid_3%3A4654). - -[![Latest Stable Version](https://poser.pugx.org/drush/drush/v/stable.png)](https://packagist.org/packages/drush/drush) [![Total Downloads](https://poser.pugx.org/drush/drush/downloads.png)](https://packagist.org/packages/drush/drush) [![Latest Unstable Version](https://poser.pugx.org/drush/drush/v/unstable.png)](https://packagist.org/packages/drush/drush) [![License](https://poser.pugx.org/drush/drush/license.png)](https://packagist.org/packages/drush/drush) - -!!! note - - Go to the [Drush 8](https://docs.drush.org/en/8.x) or [Drush 9](https://docs.drush.org/en/9.x) if you want prior version of Drush. - - -Resources ------------ -* [Install documentation](https://docs.drush.org/en/master/install/) -* [General documentation](https://docs.drush.org/) -* [API Documentation](https://www.drush.org/api/master/) -* [Drush packages available via Composer](https://packagist.org/?query=drush) -* [A list of modules that include Drush integration](https://www.drupal.org/project/project_module?f[2]=im_vid_3%3A4654&solrsort=ds_project_latest_release+desc) -* [Testing Drush](https://github.com/drush-ops/drush/blob/master/tests/README.md) or your own Drush extensions with [PHPUnit](https://github.com/sebastianbergmann/phpunit). - -Support ------------ - -Please take a moment to review the rest of the information in this file before -pursuing one of the support options below. - -* Post support requests to [Drupal Answers](https://drupal.stackexchange.com/questions/tagged/drush). -* Bug reports and feature requests should be reported in the [GitHub Drush Issue Queue](https://github.com/drush-ops/drush/issues). -* Use pull requests (PRs) to contribute to Drush. diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 0000000000..32d46ee883 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/misc/favicon.ico b/misc/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..8b2ee334fd28f71fb22eea9c63119f0ebb74596d GIT binary patch literal 1150 zcmZvaX-pGA6vu~nkQfuhit!5NP~+y^$YkKLwz5Foz0CNoope(!a@)h9!hN}LPCWo zE3=@ovH~SWBg9d2F;fr#fB*5Q-&fPf^Q?V%&2f7F1_NTEBM}`P1%)C5t5>f=Vq!d& zEYU(PmvOb(SY+s&;g4@$NBHu+-7S0c^!seSe31;JqoXtoIGs)$InsdQ;v#f)-GIyG zLd~Y~4xWAT;I77g_&~iWN9{^U7K33HA}dP`x7*F}e2u22;~dMrTh^@_{qe&+kuFJn zWuZ$VN#eM)G$~}Vbo#Gy*lbnk>FI&P;ebk|L_$J5(q(CAXlOu8R0I@^`2DsD^EvyL zJl9H%0-4eUP-HAZW~K^iwVEmuN~Mykm71E0-BX1Dx{~UaeGLNkHyv2^CiCgv-@o&oAZ|kM7^d^}YK%>uYIGCidQJt+g5po~~G|>c4%pqrf-ryZ$97#6$IVHX(QXsK))# SZff~4=J)>_XBp2fLVg3mb7kQG literal 0 HcmV?d00001 diff --git a/src/Commands/core/MkCommands.php b/src/Commands/core/MkCommands.php new file mode 100644 index 0000000000..375f41e877 --- /dev/null +++ b/src/Commands/core/MkCommands.php @@ -0,0 +1,177 @@ + self::REQ]) + { + $this->prepare($options['destination']); + + $application = Drush::getApplication(); + $all = $application->all(); + $namespaced = ListCommands::categorize($all); + + // Write content files + $pages = $nav = []; + foreach ($namespaced as $category => $commands) { + foreach ($commands as $command) { + $name = $command->getName(); + $filename = str_replace(':', '_', $name) . '.md'; + $pages[] = $filename; + $body = "# $name\n\n"; + if ($command->getDescription()) { + $body .= $command->getDescription() ."\n\n"; + if ($command->getHelp()) { + $body .= $command->getHelp(). "\n\n"; + } + } + if ($examples = $command->getExampleUsages()) { + $body .= "#### Examples\n\n"; + foreach ($examples as $key => $value) { + $body .= '- ' . $key . '. ' . $value . "\n"; + } + $body .= "\n"; + } + if ($args = $command->getDefinition()->getArguments()) { + $body .= "#### Arguments\n\n"; + foreach ($args as $arg) { + $body .= '- **' . $arg->getName() . '**. ' . $arg->getDescription() . "\n"; + } + $body .= "\n"; + } + if ($opts = $command->getDefinition()->getOptions()) { + $body .= "#### Options\n\n"; + $body .= "!!! note \"Tip\"\n\n An option value without square brackets is mandatory. Any default value is listed at description end.\n\n"; + foreach ($opts as $opt) { + // @todo more rich key and default value + $opt_array = self::optionToArray($opt); + $body .= '- **' . HelpCLIFormatter::formatOptionKeys($opt_array) . '**. ' . HelpCLIFormatter::formatOptionDescription($opt_array) . "\n"; + } + $body .= "\n"; + } + if ($topics = $command->getTopics()) { + $body .= "#### Topics\n\n"; + foreach ($topics as $value) { + $body .= "- `drush $value`\n"; + } + $body .= "\n"; + } + if ($aliases = $command->getAliases()) { + $body .= "#### Aliases\n\n"; + foreach ($aliases as $value) { + $body .= '- ' . $value . "\n"; + } + $body .= "\n"; + } + file_put_contents(Path::join($options['destination'], 'docs', $filename), $body); + } + $this->logger()->info('Found {pages} pages in {cat}', ['pages' => count($pages), 'cat' => $category]); + $nav[] = [$category => $pages]; + unset($pages); + } + + $this->writeyml($nav, $options['destination']); + } + + /** + * Write mkdocs.yml. + * + * @param $nav + * @param $dest + */ + protected function writeyml($nav, $dest) + { + // Write yml file. + $mkdocs = [ + 'site_name' => 'Drush Commands', + 'site_author' => 'Moshe Weitzman', + 'repo_name' => 'GitHub', + 'repo_url' => 'https://github.com/drush-ops/drush', + 'edit_uri' => '', + 'theme' => [ + 'name' => 'readthedocs', + ], + 'site_url' => 'http://commands.drush.org', + 'markdown_extensions' => [ + ['toc' => [ + 'toc_depth' => 0, + 'permalink' => true, + ]], + ['admonition' => []], + ], + 'nav' => $nav, + ]; + $yaml = Yaml::dump($mkdocs, PHP_INT_MAX, 2); + file_put_contents(Path::join($dest, 'mkdocs.yml'), $yaml); + } + + /** + * Empty target directories. + * + * @param $destination + */ + protected function prepare($destination) + { + $fs = new Filesystem(); + $dest = $destination; + if ($fs->exists($dest)) { + drush_delete_dir_contents($dest); + } + $fs->mkdir($dest); + $docs_dir = Path::join($dest, 'docs'); + $fs->mkdir($docs_dir); + $favicon_dir = Path::join($dest, 'docs', 'img'); + $fs->mkdir($favicon_dir); + $fs->copy('../misc/favicon.ico', Path::join($favicon_dir, 'favicon.ico')); + $fs->copy('../docs/index.md', Path::join($docs_dir, 'index.md')); + // $fs->copy('../drush_logo-black.png', Path::join($docs_dir, 'logo.png')); + } + + /** + * Build an array since thats what HelpCLIFormatter expects. + * + * @param \Symfony\Component\Console\Input\InputOption $opt + * + * @return array + */ + public static function optionToArray(InputOption $opt) + { + $return = [ + 'name' => '--' . $opt->getName(), + 'accept_value' => $opt->acceptValue(), + 'is_value_required' => $opt->isValueRequired(), + 'shortcut' => $opt->getShortcut(), + 'description' => $opt->getDescription(), + ]; + if ($opt->getDefault()) { + $return['defaults'] = (array)$opt->getDefault(); + } + return $return; + } +} diff --git a/src/Commands/help/ListCommands.php b/src/Commands/help/ListCommands.php index 0faa1791f3..b378524412 100644 --- a/src/Commands/help/ListCommands.php +++ b/src/Commands/help/ListCommands.php @@ -188,7 +188,7 @@ public function renderListRaw($namespaced) * @param Command[] $all * @param string $separator * - * @return array + * @return Command[] */ public static function categorize($all, $separator = ':') { diff --git a/src/Commands/pm/SecurityUpdateCommands.php b/src/Commands/pm/SecurityUpdateCommands.php index b33a126452..eb0b28d880 100644 --- a/src/Commands/pm/SecurityUpdateCommands.php +++ b/src/Commands/pm/SecurityUpdateCommands.php @@ -162,7 +162,7 @@ protected function calculateSecurityUpdates($composer_lock_data, $security_advis * @return UnstructuredData * @throws \Exception * @command pm:security-php - * @aliases sec-php,pm:security-php + * @aliases sec-php,pm-security-php * @bootstrap none * * @usage drush pm:security-php --format=json diff --git a/sut/drush/Commands/FixtureCommands.php b/sut/drush/Commands/FixtureCommands.php index 0ea9d40d04..9b2f076200 100644 --- a/sut/drush/Commands/FixtureCommands.php +++ b/sut/drush/Commands/FixtureCommands.php @@ -19,6 +19,7 @@ class FixtureCommands extends DrushCommands * * @command unit-eval * @bootstrap max + * @hidden */ public function drushUnitEval($code) { @@ -28,6 +29,7 @@ public function drushUnitEval($code) /** * Return options as function result. * @command unit-return-options + * @hidden */ public function drushUnitReturnOptions($arg = '', $options = ['x' => 'y', 'data' => [], 'format' => 'yaml']) { @@ -38,6 +40,7 @@ public function drushUnitReturnOptions($arg = '', $options = ['x' => 'y', 'data' /** * Return original argv as function result. * @command unit-return-argv + * @hidden */ public function drushUnitReturnArgv(array $args) {