Add reference page for mc du (#783)

Create a new reference page for `mc du` and link it in the list of `mc`
commands.

Staged:

http://192.241.195.202:9000/staging/DOCS-764/linux/html/reference/minio-mc/mc-du.html

Includes drive-by fixes to make the _Optional_ notations appear in a
more consistent manner. (Including several otherwise unrelated pages.)
There's more opportunistic fixes here than I might normally do in the
same PR, but seemed better to get it over with.

Fixes https://github.com/minio/docs/issues/764

---------

Co-authored-by: Ravind Kumar <ravind@min.io>

source/includes/common-minio-mc.rst

@@ -30,7 +30,7 @@ This command supports only global flags
 .. start-minio-mc-s3-compatibility
 
 The :program:`mc` commandline tool is built for compatibility with the AWS S3
-API and is tested MinIO and AWS S3 for expected functionality and behavior.
+API and is tested with MinIO and AWS S3 for expected functionality and behavior.
 
 MinIO provides no guarantees for other S3-compatible services, as their S3 API
 implementation is unknown and therefore unsupported. While :program:`mc`
@@ -47,4 +47,4 @@ commands *may* work as documented, any such usage is at your own risk.
 Copy the example to a text editor and modify as-needed before running the
 command in the terminal/shell.
 
-.. end-minio-syntax
+.. end-minio-syntax

source/includes/facts-versioning.rst

@@ -1,6 +1,6 @@
 .. start-rewind-desc
 
-*Optional* Directs |command| to operate only on the object version(s) that
+Directs |command| to operate only on the object version(s) that
 existed at specified point-in-time.
 
 - To rewind to a specific date in the past, specify the date as an
@@ -17,7 +17,7 @@ that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
 
 .. start-versions-desc
 
-*Optional* Directs |command| to operate on all object versions that exist in the
+Directs |command| to operate on all object versions that exist in the
 bucket.
 
 |versions| requires that the specified |alias| be an S3-compatible service
@@ -44,4 +44,4 @@ that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
    |command| requires :ref:`bucket versioning <minio-bucket-versioning>` to
    use this feature. Use :mc:`mc version` to enable versioning on a bucket.
 
-.. end-versioning-admonition
+.. end-versioning-admonition

source/reference/minio-mc.rst

@@ -203,6 +203,11 @@ The following table lists :mc-cmd:`mc` commands:
      - .. include:: /reference/minio-mc/mc-diff.rst
           :start-after: start-mc-diff-desc
           :end-before: end-mc-diff-desc
+
+   * - :mc:`mc du`
+     - .. include:: /reference/minio-mc/mc-du.rst
+          :start-after: start-mc-du-desc
+          :end-before: end-mc-du-desc
      
    * - | :mc:`mc encrypt clear`
        | :mc:`mc encrypt info`
@@ -566,6 +571,7 @@ All :ref:`commands <minio-mc-commands>` support the following global options:
    /reference/minio-mc/mc-cat
    /reference/minio-mc/mc-cp
    /reference/minio-mc/mc-diff
+   /reference/minio-mc/mc-du
    /reference/minio-mc/mc-encrypt
    /reference/minio-mc/mc-event
    /reference/minio-mc/mc-find
@@ -594,4 +600,4 @@ All :ref:`commands <minio-mc-commands>` support the following global options:
    /reference/minio-mc/mc-undo
    /reference/minio-mc/mc-update
    /reference/minio-mc/mc-version
-   /reference/minio-mc/mc-watch
+   /reference/minio-mc/mc-watch

source/reference/minio-mc/mc-cat.rst

@@ -91,7 +91,7 @@ Parameters
       mc cat ~/data/object.txt
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc

source/reference/minio-mc/mc-cp.rst

@@ -243,7 +243,7 @@ Parameters
    Requires specifying :mc-cmd:`~mc cp --retention-duration`.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -459,4 +459,4 @@ S3 Compatibility
 
 .. include:: /includes/common-minio-mc.rst
    :start-after: start-minio-mc-s3-compatibility
-   :end-before: end-minio-mc-s3-compatibility
+   :end-before: end-minio-mc-s3-compatibility

source/reference/minio-mc/mc-du.rst

@@ -0,0 +1,202 @@
+.. _minio-mc-du:
+
+==========
+``mc du``
+==========
+
+.. default-domain:: minio
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+.. mc:: mc du
+
+.. Replacement substitutions
+
+.. |command| replace:: :mc:`mc du`
+.. |rewind| replace:: :mc-cmd:`~mc du --rewind`
+.. |versions| replace:: :mc-cmd:`~mc du --versions`
+.. |alias| replace:: :mc-cmd:`~mc du ALIAS`
+
+Syntax
+------
+
+.. start-mc-du-desc
+
+The :mc:`mc du` command summarizes the disk usage of buckets and folders. 
+You can also use :mc:`~mc du` against the local filesystem to produce similar results as the ``du`` command. 
+
+.. end-mc-du-desc
+
+.. tab-set::
+
+   .. tab-item:: EXAMPLE
+
+      The following command prints the disk usage of the ``mybucket`` bucket on the ``myminio`` MinIO deployment:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc du play/mybucket
+
+      The output resembles the following:
+      
+      .. code-block:: shell
+
+         825KiB	3 objects        mybucket
+
+   .. tab-item:: SYNTAX
+
+      The :mc:`mc du` command has the following syntax:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc [GLOBALFLAGS] du              \
+                          [--depth]       \
+                          [--encrypt-key] \
+                          [--recursive]   \
+                          [--rewind]      \
+                          [--versions]    \
+                          ALIAS [ALIAS ...]
+
+      .. include:: /includes/common-minio-mc.rst
+         :start-after: start-minio-syntax
+         :end-before: end-minio-syntax
+
+
+Parameters
+~~~~~~~~~~
+
+.. mc-cmd:: ALIAS
+   :required:
+   
+   The :ref:`alias <alias>` of a MinIO deployment and the full path to the folder. For example:
+
+   .. code-block:: shell
+
+      mc du myminio/mybucket
+
+   You can specify multiple buckets and folders on the same or different MinIO deployment. For example:
+
+   .. code-block:: shell
+
+      mc du myminio/mybucket myminio/myotherbucket/myfolder
+
+   For a folder on a local filesystem, specify the full path to that folder. For example:
+
+   .. code-block:: shell
+
+      mc du ~/data/images
+
+.. mc-cmd:: --depth, d
+   :optional:
+
+   Print the total for all folders N or fewer levels below the path specified in the command. Default is 0, for the specified path only.
+
+.. mc-cmd:: --encrypt-key
+   :optional:
+
+   Encrypt or decrypt objects using server-side encryption with client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
+
+   - Each ``KEY`` represents a bucket or object.
+   - Each ``VALUE`` represents the data key to use for encrypting object(s).
+
+   Enclose the entire list of key-value pairs passed to :mc-cmd:`~mc du --encrypt-key` in double quotes ``"``.
+
+   :mc-cmd:`~mc du --encrypt-key` can use the ``MC_ENCRYPT_KEY`` environment variable for retrieving a list of encryption key-value pairs as an alternative to specifying them on the command line.
+
+.. mc-cmd:: --recursive, r
+   :optional:
+
+   Recursively print the total for each bucket or child folder.
+
+.. mc-cmd:: --rewind
+   :optional:
+
+   .. include:: /includes/facts-versioning.rst
+      :start-after: start-rewind-desc
+      :end-before: end-rewind-desc
+
+   Use :mc-cmd:`~mc du --rewind` and :mc-cmd:`~mc du --versions` together to show the disk usage for those object versions which existed at a specific point in time.
+
+.. mc-cmd:: --versions
+   :optional:
+
+   .. include:: /includes/facts-versioning.rst
+      :start-after: start-versions-desc
+      :end-before: end-versions-desc
+
+   Use :mc-cmd:`~mc du --versions` and :mc-cmd:`~mc du --rewind` together to show the disk usage for those object versions which existed at a specific point in time.
+
+
+Global Flags
+~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-mc.rst
+   :start-after: start-minio-mc-globals
+   :end-before: end-minio-mc-globals
+
+Examples
+--------
+
+View the Disk Usage for a Bucket or Folder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc:`mc du` to print a summary of the disk usage for a bucket or folder:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc du ALIAS/PATH
+
+- Replace :mc-cmd:`ALIAS <mc du ALIAS>` with the  :mc:`alias <mc alias>` of the S3-compatible host.
+
+- Replace :mc-cmd:`PATH <mc du ALIAS>` with the path to the bucket or folder on the S3-compatible host.
+
+View the Disk Usage at a Point-In-Time
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc du --rewind` to print a summary of disk usage at a specific point-in-time in the past:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc du --rewind DURATION ALIAS/PATH
+
+- Replace :mc-cmd:`DURATION <mc du --rewind>` with the desired point-in-time in the past. For example, specify ``30d`` to show the disk usage 30 days prior to the current date.
+
+- Replace :mc-cmd:`ALIAS <mc du ALIAS>` with the 
+  :mc:`alias <mc alias>` of the S3-compatible host.
+
+- Replace :mc-cmd:`PATH <mc du ALIAS>` with the path to the bucket or folder on the S3-compatible host.
+
+.. include:: /includes/facts-versioning.rst
+   :start-after: start-versioning-admonition
+   :end-before: end-versioning-admonition
+
+View the Disk Usage Recursively
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use :mc-cmd:`mc du --recursive` to print a summary for each folder recursively:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc du --recursive ALIAS/PATH
+
+- Replace :mc-cmd:`ALIAS <mc du ALIAS>` with the :mc:`alias <mc alias>` of the S3-compatible host.
+
+- Replace :mc-cmd:`PATH <mc du ALIAS>` with the path to the bucket or folder on the S3-compatible host.
+
+
+Behavior
+--------
+
+S3 Compatibility
+~~~~~~~~~~~~~~~~
+
+.. include:: /includes/common-minio-mc.rst
+   :start-after: start-minio-mc-s3-compatibility
+   :end-before: end-minio-mc-s3-compatibility

source/reference/minio-mc/mc-head.rst

@@ -116,7 +116,7 @@ Parameters
    as an alternative to specifying them on the command line.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc

source/reference/minio-mc/mc-legalhold-clear.rst

@@ -81,7 +81,7 @@ Parameters
    :mc-cmd:`~mc legalhold clear ALIAS` bucket or bucket prefix.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc

source/reference/minio-mc/mc-legalhold-info.rst

@@ -80,7 +80,7 @@ Parameters
    :mc-cmd:`~mc legalhold info ALIAS` bucket or bucket prefix.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc

source/reference/minio-mc/mc-legalhold-set.rst

@@ -81,7 +81,7 @@ Parameters
    :mc-cmd:`~mc legalhold set ALIAS` bucket or bucket prefix.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc

source/reference/minio-mc/mc-ls.rst

@@ -42,7 +42,7 @@ results as the ``ls`` command.
 
          mc ls --recursive --versions myminio/mydata
 
-      The output resembles the following::
+      The output resembles the following:
 
       .. code-block:: shell
 
@@ -116,7 +116,7 @@ Parameters
    :mc-cmd:`~mc ls ALIAS`.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
    
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -127,7 +127,7 @@ Parameters
    versions which existed at a specific point in time.
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-retention-clear.rst

@@ -109,7 +109,7 @@ Parameters
    Mutually exclusive with :mc-cmd:`~mc retention clear --version-id`.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -129,7 +129,7 @@ Parameters
    - :mc-cmd:`~mc retention clear --recursive`
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-retention-info.rst

@@ -116,7 +116,7 @@ Parameters
    Mutually exclusive with :mc-cmd:`~mc retention info --version-id`.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -136,7 +136,7 @@ Parameters
    - :mc-cmd:`~mc retention info --recursive`
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-retention-set.rst

@@ -160,7 +160,7 @@ Parameters
    Mutually exclusive with :mc-cmd:`~mc retention set --version-id`.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -182,7 +182,7 @@ Parameters
    - :mc-cmd:`~mc retention set --recursive`
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-rm.rst

@@ -235,7 +235,7 @@ Parameters
    Mutually exclusive with :mc-cmd:`mc rm --version-id`
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -247,7 +247,7 @@ Parameters
    *Optional* Read object names or buckets from ``STDIN``.
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-stat.rst

@@ -120,14 +120,14 @@ Parameters
    specified to :mc-cmd:`~mc stat ALIAS`.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
       :end-before: end-rewind-desc
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc
@@ -192,4 +192,4 @@ S3 Compatibility
 
 .. include:: /includes/common-minio-mc.rst
    :start-after: start-minio-mc-s3-compatibility
-   :end-before: end-minio-mc-s3-compatibility
+   :end-before: end-minio-mc-s3-compatibility

source/reference/minio-mc/mc-tag-list.rst

@@ -73,14 +73,14 @@ Parameters
       mc tag list myminio/mybucket/object.txt
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
       :end-before: end-rewind-desc
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-tag-remove.rst

@@ -72,14 +72,14 @@ Parameters
       mc tag remove myminio/mybucket/object.txt
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
       :end-before: end-rewind-desc
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-tag-set.rst

@@ -87,14 +87,14 @@ Parameters
       mc tag set myminio/mybucket/object.txt "key1=value1&key2=value2"
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
       :end-before: end-rewind-desc
 
 .. mc-cmd:: --versions
-   
+   :optional:   
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-versions-desc

source/reference/minio-mc/mc-tree.rst

@@ -96,7 +96,7 @@ Parameters
    output.
 
 .. mc-cmd:: --rewind
-   
+   :optional:
 
    .. include:: /includes/facts-versioning.rst
       :start-after: start-rewind-desc
@@ -125,4 +125,4 @@ S3 Compatibility
 
 .. include:: /includes/common-minio-mc.rst
    :start-after: start-minio-mc-s3-compatibility
-   :end-before: end-minio-mc-s3-compatibility
+   :end-before: end-minio-mc-s3-compatibility