Move Sami build to Github actions (#4474)

.github/workflows/commands.yml → .github/workflows/main.yml

@@ -1,4 +1,4 @@
-name: Build Commands Site
+name: Build static sites
 
 # Controls when the action will run. Triggers the workflow on push or pull request
 # events but only for the master branch
@@ -10,7 +10,7 @@ on:
 
 jobs:
   build:
-    name: Build and Deploy
+    name: Build and Push
     runs-on: ubuntu-latest
     steps:
       - name: Checkout master
@@ -54,20 +54,46 @@ jobs:
         run: composer mk:docs
 
       - name: Mkdocs build
-        run: cd build-commands && mkdocs build -v --site-dir ../gh-pages/commands/10.x
+        run: cd build-commands && mkdocs build --site-dir ../gh-pages/commands/10.x
 
-      - name: Commit and Push to gh-pages
+      - name: Commit Commands to gh-pages
         run: |
           cd gh-pages
 
           git config --local user.email "actions@github.com"
-          git config --local user.name "GitHub Action"
+          git config --local user.name "Drush Documentation Bot"
 
           git add -A .
 
           if git diff-index --quiet HEAD --; then
             echo "No changes..."
           else
-            git commit -m "[CI] build commands static site"
-            git push
+            git commit -m "[CI] Build Commands static site"
           fi
+
+      - name: Install Sami
+        run: composer sami-install
+
+      - name: Sami build
+        # We have Sami parse errors so ignore return value: https://stackoverflow.com/questions/35452147/allow-non-zero-return-codes-in-travis-ci-yml
+        run: |
+          rm -rf gh-pages/api
+          composer api || true
+
+      - name: Commit API to gh-pages
+        run: |
+          cd gh-pages
+
+          git config --local user.email "actions@github.com"
+          git config --local user.name "Drush Documentation Bot"
+
+          git add -A .
+
+          if git diff-index --quiet HEAD --; then
+            echo "No changes..."
+          else
+            git commit -m "[CI] Build API static site"
+          fi
+
+      - name: Git Push
+        run: cd gh-pages && git push

README.md

@@ -6,7 +6,7 @@ Resources
 -----------
 * [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/)
+* [Drush 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)

sami-config.php

@@ -18,17 +18,18 @@
 ;
 
 // generate documentation for all v2.0.* tags, the 2.0 branch, and the master one
-$versions = GitVersionCollection::create($dir)
-  // ->addFromTags('8.*')
- //  ->add('8.x', '8.x branch')
-  ->add('master', 'Master branch')
-;
+// $versions = GitVersionCollection::create($dir)
+//   ->addFromTags('8.*')
+//   ->add('8.x', '8.x branch')
+// Sami actively checks out each ref listed here.
+//   ->add('no-travis', 'Master branch')
+//;
 
 return new Sami($iterator, array(
   // 'theme'                => 'symfony',
-  'versions'             => $versions,
+  //'versions'             => $versions,
   'title'                => 'Drush API',
-  'build_dir'            => __DIR__.'/api/%version%',
+  'build_dir'            => __DIR__.'/gh-pages/api/%version%',
   'cache_dir'            => __DIR__.'/.sami-cache/%version%',
   'remote_repository'    => new GitHubRemoteRepository('drush-ops/drush', dirname($dir)),
   'default_opened_level' => 2,

src/Commands/core/MkCommands.php

@@ -65,7 +65,6 @@ public function docs($options = ['destination' => self::REQ])
                 }
                 if ($args = $command->getDefinition()->getArguments()) {
                     $body .= "#### Arguments\n\n";
-                    $body .= "!!! note \"Tip\"\n\n    - An argument name without square brackets is mandatory.\n    - An ellipsis indicates that an argument accepts multiple values separated by a space.\n\n";
                     foreach ($args as $arg) {
                         $arg_array = self::argToArray($arg);
                         $body .= '- **' . HelpCLIFormatter::formatArgumentName($arg_array) . '**. ' . $arg->getDescription() . "\n";
@@ -74,7 +73,6 @@ public function docs($options = ['destination' => self::REQ])
                 }
                 if ($opts = $command->getDefinition()->getOptions()) {
                     $body .= "#### Options\n\n";
-                    $body .= "!!! note \"Tip\"\n\n    - An option value without square brackets is mandatory.\n    - Any default value is listed at description end.\n\n";
                     foreach ($opts as $opt) {
                         if (!HelpCLIFormatter::isGlobalOption($opt->getName())) {
                             $opt_array = self::optionToArray($opt);
@@ -97,6 +95,11 @@ public function docs($options = ['destination' => self::REQ])
                     }
                     $body .= "\n";
                 }
+                $body .= '!!! note "Legend"' . "\n" . <<<EOT
+    - An argument or option with square brackets is optional.
+    - Any default value is listed at end of arg/option description.
+    - An ellipsis indicates that an argument accepts multiple values separated by a space.
+EOT;
                 file_put_contents(Path::join($options['destination'], 'docs', $filename), $body);
             }
             $this->logger()->info('Found {pages} pages in {cat}', ['pages' => count($pages), 'cat' => $category]);