-
-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add a new mk:docs command to auto-build an official Drush Commands we…
…b site (#4472)
- Loading branch information
Showing
10 changed files
with
264 additions
and
33 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ../README.md |
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,177 @@ | ||
| <?php | ||
|
|
||
| namespace Drush\Commands\core; | ||
|
|
||
| use Consolidation\SiteAlias\SiteAliasManagerAwareTrait; | ||
| use Drush\Commands\DrushCommands; | ||
| use Drush\Commands\help\HelpCLIFormatter; | ||
| use Drush\Commands\help\ListCommands; | ||
| use Drush\Drush; | ||
| use Drush\SiteAlias\SiteAliasManagerAwareInterface; | ||
| use Symfony\Component\Console\Input\InputOption; | ||
| use Symfony\Component\Filesystem\Filesystem; | ||
| use Symfony\Component\Yaml\Yaml; | ||
| use Webmozart\PathUtil\Path; | ||
|
|
||
| class MkCommands extends DrushCommands implements SiteAliasManagerAwareInterface | ||
| { | ||
|
|
||
| use SiteAliasManagerAwareTrait; | ||
|
|
||
| /** | ||
| * Build an mkdocs site. | ||
| * | ||
| * @option destination The target directory where files should be written. A relative path starts at Drupal root. | ||
| * | ||
| * @command mk:docs | ||
| * @bootstrap max | ||
| * @hidden | ||
| * @usage drush mk:docs --destination=/tmp/build | ||
| * Build an mkdocs site at /tmp/build directory. | ||
| */ | ||
| public function docs($options = ['destination' => 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 .= '- <code>' . $key . '</code>. ' . $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; | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters