Add docs for CLI rename slug task (#228)

* Add docs for CLI rename slug task
* Add links from other related pages, and examples

admin-manual/maintenance/cli-tools.rst

@@ -1090,6 +1090,12 @@ task described above.
 
    * :ref:`rename-title-slug`
 
+   Users can also use the CLI rename-slug tool if they want to update one or
+   more slugs via the command line. For more infomation, see:
+
+   * :ref:`cli-rename-slugs`
+
+
 Finally, :term:`static pages <static page>`, or permanent links, include a
 slug :term:`field` option, but only slugs for new static pages can be edited
 by users; the slugs for the default :term:`Home page` and :term:`About page`
@@ -1114,6 +1120,57 @@ AtoM, see: :ref:`manage-static-pages`.
    For developers interested in seeing the code where slugs are handled in
    AtoM, see ``/lib/model/QubitSlug.php``
 
+.. _cli-rename-slugs:
+
+Rename slugs via command line
+=============================
+
+This command line tool can be used to rename existing slugs in AtoM. It offers
+the ability to either rename a single slug, or to run a batch rename using a
+csv file.
+
+.. code:: bash
+
+   php symfony tools:rename-slug [<old-slug> <new-slug>] [--csv=<path-to-file.csv>]
+
+**Task options**
+
+.. image:: images/cli-rename-slug.*
+   :align: center
+   :width: 70%
+   :alt: An image of the CLI options when invoking the tools:rename-slug command
+
+By entering ``php symfony help tools:rename-slug`` into the command-line, you
+see the options and descriptions available on this tool, as pictured above.
+
+The ``--application``, ``--env``, and ``connection`` options **should not be
+used** - AtoM requires the uses of the pre-set defaults for symfony to be
+able to execute the task.
+
+When used without any other options, the rename slugs task expects two
+arguments: an existing slug, and a new name for the existing slug. For example,
+to rename my-example-slug to new-slug, the following command should be run:
+``php symfony tools:rename-slug my-example-slug new-slug``.
+
+The ``--csv`` option can be used to provide a CSV file to use for a batch
+import. The supplied CSV file only needs two columns: an oldSlug column
+(containing the existing slugs), and a newSlug column. Here is an example CSV:
+
+.. image:: images/cli-rename-example.*
+   :align: center
+   :width: 70%
+   :alt: An image of an example CSV file used for a rename-slug command
+
+For example, to use a CSV file to batch update slugs, this command can be run:
+``php symfony tools:rename-slug --csv="path/to/my/slug-file.csv"``
+
+.. SEEALSO::
+
+   * :ref:`rename-title-slug`
+   * :ref:`slugs-in-atom`
+   * :ref:`description-permalinks`
+   * :ref:`cli-generate-slugs`
+
 .. _cli-normalize-taxonomy:
 
 Taxonomy normalization

user-manual/add-edit-content/archival-descriptions.rst

@@ -1435,6 +1435,14 @@ the filename of a linked digital object will be covered on the
    specific description on an external website, they may break after changing
    the slug.
 
+.. SEEALSO::
+
+   Users can also update slug(s) via a command line tool. For more information,
+   see:
+
+   * :ref:`cli-rename-slugs`
+
+
 :ref:`Back to top <archival-descriptions>`
 
 .. _view-modification-history:

user-manual/administer/settings.rst

@@ -699,6 +699,13 @@ For further context on slugs in AtoM, see: :ref:`slugs-in-atom`
 
    * :ref:`rename-title-slug`
 
+.. SEEALSO::
+
+   Users can also update slug(s) via a command line tool. For more information,
+   see:
+
+   * :ref:`cli-rename-slugs`
+
 .. _permissive-slugs:
 
 Use any valid URI path segment and uppercase character in slugs