Unify the commands and docs sites at www.drush.org (drush-ops#4490)

.github/workflows/main.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install mkdocs pymdown-extensions
+          pip install mkdocs-material pymdown-extensions git+https://gitlab.com/blacs30/mkdocs-edit-url.git
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
@@ -54,9 +54,9 @@ jobs:
         run: composer mk:docs
 
       - name: Mkdocs build
-        run: cd build-commands && mkdocs build --site-dir ../gh-pages/commands/10.x
+        run: mkdocs build --site-dir gh-pages
 
-      - name: Commit Commands to gh-pages
+      - name: Commit mkdocs pages to gh-pages
         run: |
           cd gh-pages
 
@@ -68,7 +68,7 @@ jobs:
           if git diff-index --quiet HEAD --; then
             echo "No changes..."
           else
-            git commit -m "[CI] Build Commands static site"
+            git commit -m "[CI] Build mkdocs static site"
           fi
 
       - name: Install Sami
@@ -95,5 +95,5 @@ jobs:
             git commit -m "[CI] Build API static site"
           fi
 
-      - name: Git Push
-        run: cd gh-pages && git push
+#      - name: Git Push
+#        run: cd gh-pages && git push

.gitignore

@@ -2,10 +2,12 @@ tests/phpunit.xml
 vendor
 box.phar
 drush.phar
-#The mkdocs output directory.
+#The mkdocs output directory and generated file.
 site
+gh-pages
+mkdocs.yml
 #The Commands site output directory.
-build-commands
+docs/commands
 #The sami output directories
 api
 .sami-cache

README.md

@@ -1,13 +1,13 @@
-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](https://www.drush.org/commands/10.x/generate/), 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](commands/10.x/generate.md), 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) <a href="https://circleci.com/gh/drush-ops/drush"><img src="https://circleci.com/gh/drush-ops/drush.svg?style=shield"></a> [![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/) ([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/))
-* [Drush Commands](https://www.drush.org/commands/10.x/)
-* [API Documentation](http://www.drush.org/api/master/index.html)
+* [Installing and Upgrading](install.md) ([Drush 8](https://docs.drush.org/en/8.x/install/))
+* [General Documentation](usage.md) ([Drush 8](https://docs.drush.org/en/8.x/install/))
+* [Drush Commands](commands/10.x/all.md)
+* [API Documentation](/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)
 * Drush comes with a [full test suite](https://github.com/drush-ops/drush/blob/master/tests/README.md) powered by [PHPUnit](https://github.com/sebastianbergmann/phpunit). Each commit gets tested by our CI bots.

composer.json

@@ -98,7 +98,7 @@
     ],
     "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",
+    "mk:docs": "./drush --uri=dev -v mk:docs --destination=commands/10.x",
     "sut": "./drush --uri=dev",
     "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",

docs/bootstrap.md

@@ -13,7 +13,7 @@ Prior to bootstrapping, Drush goes through the "preflight" process, where the fo
 1. The site-alias included on the commandline is loaded if present.
 1. The local selected site is determined, if any.
 1. [Dependency injection](dependency-injection.md) is done.
-1. Global commandfiles are loaded. Commandfiles with a drush.services.yml are loaded later, during bootstrap @full. 
+1. Global commandfiles are loaded. Commandfiles with a drush.services.yml are loaded later, during `bootstrap @full`. 
 1. The command is dispatched via the Symfony Console component.
 
 Bootstrapping is done from a Symfony Console command hook. The different bootstrap levels are discribed below.

docs/commands.md

@@ -1,5 +1,4 @@
-Creating Custom Drush Commands
-==============================
+# Creating Custom Drush Commands
 
 Creating a new Drush command or porting a legacy command is easy. Follow the steps below.
 
@@ -13,11 +12,10 @@ Creating a new Drush command or porting a legacy command is easy. Follow the ste
 1. Write PHPUnit tests based on [Drush Test Traits](https://github.com/drush-ops/drush/tree/master/tests#drush-test-traits).
 1. Once your two files are ready, run `drush cr` to get your command recognized by the Drupal container.
 
-Specifying the Services File
-================================
+## Specifying the Services File
 
 A module's composer.json file stipulates the filename where the Drush services (e.g. the Drush command files) are defined. The default services file is `drush.services.yml`, which is defined in the extra section of the composer.json file as follows:
-```
+```json
   "extra": {
     "drush": {
       "services": {
@@ -27,7 +25,7 @@ A module's composer.json file stipulates the filename where the Drush services (
   }
 ```
 If for some reason you need to load different services for different versions of Drush, simply define multiple services files in the `services` section. The first one found will be used. For example:
-```
+```json
   "extra": {
     "drush": {
       "services": {
@@ -43,9 +41,7 @@ It is also possible to use [version ranges](https://getcomposer.org/doc/articles
 
 In Drush 9, the default services file, `drush.services.yml`, will be used in instances where there is no `services` section in the Drush extras of the project's composer.json file. In Drush 10, however, the services section must exist, and must name the services file to be used. If a future Drush extension is written such that it only works with Drush 10 and later, then its entry would read `"drush.services.yml": "^10"`, and Drush 9 would not load the extension's commands. It is all the same recommended that Drush 9 extensions explicitly declare their services file with an appropriate version constraint.
 
-Altering Drush Command Info
-===========================
-
+## Altering Drush Command Info
 Drush command info (annotations) can be altered from other modules. This is done by creating and registering 'command info alterers'. Alterers are class services that are able to intercept and manipulate an existing command annotation.
 
 In order to alter an existing command info, follow the steps below:
@@ -57,9 +53,7 @@ In order to alter an existing command info, follow the steps below:
 
 For an example, see the alterer class provided by the testing 'woot' module: `tests/functional/resources/modules/d8/woot/src/WootCommandInfoAlterer.php`.
 
-Site-Wide Drush Commands
-==============================
-
+## Site-Wide Drush Commands
 Commandfiles that are installed in a Drupal site and are not bundled inside a Drupal module are called 'site-wide' commandfiles. Site-wide commands may either be added directly to the Drupal site's repository (e.g. for site-specific policy files), or via `composer require`. See the [examples/Commands](https://github.com/drush-ops/drush/tree/master/examples/Commands) folder for examples. In general, it's better to use modules to carry your Drush commands, as module-based commands may [participate in Drupal's dependency injection via the drush.services.yml](#specifying-the-services-file).
 
 If you still prefer using site-wide commandfiles, here are some examples of valid commandfile names and namespaces:
@@ -79,7 +73,7 @@ Note: Make sure you do _not_ include `src` in the path to your command. Your com
 Installing commands as part of a Composer project requires that the project's type be `drupal-drush`, and that the `installer-paths` in the Drupal site's composer.json file contains `"drush/Commands/contrib/{$name}": ["type:drupal-drush"]`. It is also possible to commit projects with a similar layout using a directory named `custom` in place of `contrib`; if this is done, then the directory `custom` will not be considered to be part of the commandfile's namespace.
 
 If a site-wide commandfile is added via a Composer package, then it may declare any dependencies that it may need in its composer.json file. Site-wide commandfiles that are committed directly to a site's repository only have access to the dependencies already available in the site. Site-wide commandfiles should declare their Drush version compatibility via a `conflict` directive. For example, a Composer-managed site-wide command that works with both Drush 8 and Drush 9 might contain something similar to the following in its composer.json file:
-```
+```json
     "conflict": {
         "drush/drush": "<8.2 || >=9.0 <9.6 || >=10.0",
     }
@@ -88,32 +82,28 @@ Using `require` in place of `conflict` is not recommended.
 
 A site-wide commandfile should have tests that run with each (major) version of Drush that is supported. You may model your test suite after the [example drush extension](https://github.com/drush-ops/example-drush-extension) project, which works on Drush ^8.2 and ^9.6.
 
-Global Drush Commands
-==============================
-
+## Global Drush Commands
 Commandfiles that are not part of any Drupal site are called 'global' commandfiles. Global commandfiles are not supported by default; in order to enable them, you must configure your `drush.yml` configuration file to add an `include` search location.
 
 For example:
 
+```yaml
 drush:
   paths:
     include:
       - '${env.home}/.drush/commands'
-
+```      
 With this configuration in place, global commands may be placed as described in the Site-Wide Drush Commands section above. Global commandfiles may not declare any dependencies of their own; they may only use those dependencies already available via the autoloader.
 
-##### Tips
-1. The filename must be have a name like Commands/ExampleCommands.php
-    1. The prefix `Example` can be whatever string you want.
-    1. The file must end in `Commands.php`
-1. The directory above `Commands` must be one of: 
-    1.  A Folder listed in the 'include' option. Include may be provided via [config](#global-drush-commands) or via CLI.
-    1.  ../drush, /drush or /sites/all/drush. These paths are relative to Drupal root.
+!!! tip
+    1. The filename must be have a name like Commands/ExampleCommands.php
+        1. The prefix `Example` can be whatever string you want.
+        1. The file must end in `Commands.php`
+    1. The directory above `Commands` must be one of: 
+        1.  A Folder listed in the 'include' option. Include may be provided via [config](#global-drush-commands) or via CLI.
+        1.  ../drush, /drush or /sites/all/drush. These paths are relative to Drupal root.
 
 It is recommended that you avoid global Drush commands, and favor site-wide commandfiles instead. If you really need a command or commands that are not part of any Drupal site, consider making a stand-alone script or custom .phar instead. See [ahoy](https://github.com/ahoy-cli/ahoy), [Robo](https://github.com/consolidation/robo) and [g1a/starter](https://github.com/g1a/starter) as potential starting points.
 
-Composer packaged commands
-==============================
-
-##### Symlinked packages
-While it is good practice to make your custom commands into a Composer package, please beware that symlinked packages (by using the composer repository type [Path](https://getcomposer.org/doc/05-repositories.md#path)) will **not** be discovered by Drush. When in development, it is recommended to [specify your package's](https://github.com/drush-ops/drush/blob/master/examples/example.drush.yml#L52-L67) path in your `drush.yml` to have quick access to your commands.
+!!! warning "Symlinked packages"
+    While it is good practice to make your custom commands into a Composer package, please beware that symlinked packages (by using the composer repository type [Path](https://getcomposer.org/doc/05-repositories.md#path)) will **not** be discovered by Drush. When in development, it is recommended to [specify your package's](https://github.com/drush-ops/drush/blob/master/examples/example.drush.yml#L52-L67) path in your `drush.yml` to have quick access to your commands.

docs/config-exporting.md

@@ -21,7 +21,7 @@ The configuration override system allows you to change configuration
 values for a given instance of a site (e.g. the development server) by
 setting configuration variables in the site's settings.php file.
 For example, to change the name of a local development site:
-```
+```php
 $config['system.site']['name'] = 'Local Install of Awesome Widgets, Inc.';
 ```
 Note that the configuration override system is a Drupal feature, not

docs/cron.md

@@ -1,7 +1,7 @@
 Running Drupal cron tasks from Drush
 ====================================
 
-Drupal cron tasks are often set up to be run via a wget call to cron.php; this same task can also be accomplished via the [cron command](https://www.drush.org/commands/10.x/core_cron/), which circumvents the need to provide a web server interface to cron.
+Drupal cron tasks are often set up to be run via a wget call to cron.php; this same task can also be accomplished via the [cron command](commands/10.x/core_cron.md), which circumvents the need to provide a web server interface to cron.
 
 Quick start
 ----------

docs/css/extra.readthedocs.css

@@ -1,8 +1,4 @@
-/*Remove right hand column*/
-.wy-nav-content {
-    max-width: unset;
-}
-
-.rst-content div[role=navigation] {
-    display: none;
-}
+/* Works better on slate scheme.
+/*.md-typeset a {*/
+/*    color: hsl(231, 68%, 85%);*/
+/*}*/

docs/dependency-injection.md

@@ -9,15 +9,15 @@ Types of Injection
 There are two ways that a class can receive its dependencies. One is called “constructor injection”, and the other is called “setter injection”.
 
 *Example of constructor injection:*
-```
+```php
     public function __construct(DependencyType $service)
     {
         $this->service = $service;
     }
 ```
 
 *Example of setter injection:*
-```
+```php
     public function setService(DependencyType $service)
     {
         $this->service = $service;
@@ -29,7 +29,7 @@ Services Files
 ------------------
 
 Drush command files can request that Drupal inject services by using a drush.services.yml file. See [creating commands](commands.md) for instructions on how to use the Drupal Code Generator to create a simple command file starter with a drush.services.yml file. An initial services file will look something like this:
-```
+```yaml
 services:
   my_module.commands:
     class: \Drupal\my_module\Commands\MyModuleiCommands
@@ -45,7 +45,7 @@ Drush will also inject dependencies that it provides using a technique called in
 
 For example:
 
-```
+```php
 <?php
 namespace Drupal\my_module\Commands;
 

docs/deploycommand.md

@@ -0,0 +1,27 @@
+# Deploy
+
+The [deploy command](commands/10.x/deploy.md) standardizes how Drupal deployments work. The intent is your 
+deployment script updates the codebase for the target site and then this command 
+performs the following:
+
+```
+drush updatedb --no-cache-clear
+drush cache:rebuild
+drush config:import
+drush cache:rebuild
+drush deploy:hook
+```
+
+## Authoring update functions
+Below are the 3 types of update functions run by this command, in order. Choose the most appropriate for your need. 
+
+| Function | Drupal API | Purpose |
+| --- | --- | --- |
+| [HOOK_update_n()](https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!module.api.php/function/hook_update_N) | Not allowed | Low level changes. |
+| [HOOK_post_update_NAME()](https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Extension!module.api.php/function/hook_post_update_NAME) | Allowed | Runs *before* config is imported. |
+| [HOOK_deploy_NAME()](https://github.com/drush-ops/drush/blob/master/tests/functional/resources/modules/d8/woot/woot.deploy.php) | Allowed | Runs *after* config is imported. | 
+
+## Configuration
+
+If you need to customize this command, you should use Drush configuration for the 
+subcommands listed above (e.g. [updatedb](commands/10.x/updatedb.md), [config:import](commands/10.x/config_import.md), etc.).