Updated the help and documenation for the project. Tweaked the description and weight of all menu items to have a logical order.

Author: philipnorton42

README.md

@@ -1 +1,59 @@
 # Drupal Batch Examples
+
+Compatible with Drupal 10 and 11.
+
+This codebase contains a number of modules that show how to use the batch API
+in different ways. The modules have been split into different parts to show
+different parts of the batch API in action.
+
+Every module has a form that can be submitted to initiate the batch process.
+
+All modules have unit tests to test that the batch has run correctly.
+
+## Drupal Batch Examples
+
+A meta-module to provide a consistent navigation system for the other examples.
+
+Path: /drupal-batch-examples
+
+## Batch Form Example
+
+An example of running a batch in a self contained form.
+
+Path: `/drupal-batch-examples/batch-form-example`
+
+## Batch Class Example
+
+An example of running batch via a class. Includes Drush support.
+
+Path: `/drupal-batch-examples/batch-class-example`
+
+This module also shows how to use the batch API in Drush. The same batch process
+is run via the form and via the Drush command `drush batch_class_example:run`.
+
+## Batch Finish Example
+
+An example of using the finish property of the batch API.
+
+Path: `/drupal-batch-examples/batch-finish-example`
+
+## Batch Addition Example
+
+An example of adding a batch inside a running batch.
+
+Path: `/drupal-batch-examples/batch-addition-example`
+
+## Batch CSV Example
+
+An example of using the batch API to process a CSV file.
+
+This batch process will create nodes of the type "article", which comes with the
+standard install profile. In this case we are taking a two column CSV and using
+the first column for the title and the second column for the body content.
+
+Path: `/drupal-batch-examples/batch-csv-example`
+
+You can download the CSV needed for this form at the path
+`/drupal-batch-examples/batch-csv-example/generate-csv`, which is also linked to
+from the batch form itself. The CSV is generated from random data and so will
+be different every time you download it.

drupal_batch_examples.links.menu.yml

@@ -1,6 +1,6 @@
 drupal_batch_examples:
   title: 'Drupal Batch Examples'
   parent: system.admin
-  description: 'Drupal batch examples.'
+  description: 'Examples of using the batch API in different ways.'
   route_name: drupal_batch_examples
   weight: 1

modules/batch_addition_example/batch_addition_example.links.menu.yml

@@ -1,6 +1,6 @@
 batch_addition_example:
   title: 'Batch Addition Example'
   parent: drupal_batch_examples
-  description: 'Batch addition example.'
+  description: 'An example of adding to an batch run whilst a batch run is being processed.'
   route_name: batch_addition_example
-  weight: 2
+  weight: 4

modules/batch_addition_example/src/Form/BatchForm.php

@@ -24,6 +24,10 @@ public function getFormId() {
    * {@inheritdoc}
    */
   public function buildForm(array $form, FormStateInterface $form_state) {
+    $form['help'] = [
+      '#markup' => $this->t('This form will initiate a batch run that will add a number of additional batch runs during the first pass. Once the first batch has completed the secondary batches will be processed.'),
+    ];
+
     $form['actions'] = [
       '#type' => 'actions',
       'submit' => [

modules/batch_class_example/batch_class_example.links.menu.yml

@@ -1,6 +1,6 @@
 batch_class_example:
   title: 'Batch Class Example'
   parent: drupal_batch_examples
-  description: 'Batch class example.'
+  description: 'An example of splitting the batch out of a form and into a class.'
   route_name: batch_class_example
   weight: 2

modules/batch_class_example/src/Form/BatchForm.php

@@ -24,6 +24,10 @@ public function getFormId() {
    * {@inheritdoc}
    */
   public function buildForm(array $form, FormStateInterface $form_state) {
+    $form['help'] = [
+      '#markup' => $this->t('Submit this form to run a batch operation held in another class. This operation will run through 1000 items in chunks of 100.'),
+    ];
+
     $form['actions'] = [
       '#type' => 'actions',
       'submit' => [

modules/batch_csv_example/batch_csv_example.links.menu.yml

@@ -1,6 +1,6 @@
 batch_csv_example:
   title: 'Batch CSV Example'
   parent: drupal_batch_examples
-  description: 'Process a CSV using the batch API.'
+  description: 'This form will take a CSV file and process it in a batch to create content.'
   route_name: batch_csv_example
-  weight: 2
+  weight: 5

modules/batch_csv_example/src/Form/BatchForm.php

@@ -25,6 +25,10 @@ public function getFormId() {
    * {@inheritdoc}
    */
   public function buildForm(array $form, FormStateInterface $form_state) {
+    $form['help'] = [
+      '#markup' => $this->t('This form will run a batch operation that will import a CSV to create Article content items. The CSV is processed in the batch operation so the size of the file does not matter.'),
+    ];
+
     $form['csv_file'] = [
       '#type' => 'file',
       '#title' => $this->t('The CSV file to process'),
@@ -33,7 +37,7 @@ public function buildForm(array $form, FormStateInterface $form_state) {
 
     $form['csv_file_generate'] = [
       '#type' => 'link',
-      '#title' => $this->t('Generate a CSV file'),
+      '#title' => $this->t('Generate a CSV file containing 500 items.'),
       '#url' => Url::fromRoute('batch_csv_example.generate'),
     ];
 

modules/batch_csv_example/tests/Functional/BatchFormTest.php

@@ -2,7 +2,6 @@
 
 namespace Drupal\Tests\batch_csv_example\Functional;
 
-use Drupal\Core\File\FileExists;
 use Drupal\Tests\BrowserTestBase;
 
 /**

modules/batch_finish_example/batch_finish_example.links.menu.yml

@@ -1,6 +1,6 @@
 batch_finish_example:
   title: 'Batch Finish Example'
   parent: drupal_batch_examples
-  description: 'Batch finish example.'
+  description: 'An example of using the finish property of the batch API to stop the batch.'
   route_name: batch_finish_example
-  weight: 2
+  weight: 3

modules/batch_finish_example/src/Form/BatchForm.php

@@ -24,6 +24,10 @@ public function getFormId() {
    * {@inheritdoc}
    */
   public function buildForm(array $form, FormStateInterface $form_state) {
+    $form['help'] = [
+      '#markup' => $this->t('Submit this form to run a batch operation that will process 1000 items in batches of 100. Only one batch operation is given to the batch API, and this is called until a finish state is reached.'),
+    ];
+
     $form['actions'] = [
       '#type' => 'actions',
       'submit' => [

modules/batch_form_example/batch_form_example.links.menu.yml

@@ -1,6 +1,6 @@
 batch_form_example:
   title: 'Batch Form Example'
   parent: drupal_batch_examples
-  description: 'Batch form example.'
+  description: 'A simple example of the batch API contained within a form class.'
   route_name: batch_form_example
   weight: 1

modules/batch_form_example/src/Form/BatchForm.php

@@ -23,6 +23,10 @@ public function getFormId() {
    * {@inheritdoc}
    */
   public function buildForm(array $form, FormStateInterface $form_state) {
+    $form['help'] = [
+      '#markup' => $this->t('Submit this form to run a self contained batch operation. This operation will run through 1000 items in chunks of 100.'),
+    ];
+
     $form['actions'] = [
       '#type' => 'actions',
       'submit' => [