Merge pull request #5250 from TexasDigitalLibrary/5240-DVUploader_doc…

…umentation

DVUploader text for guides

doc/sphinx-guides/source/admin/dataverses-datasets.rst

@@ -29,7 +29,7 @@ Removes a link between a dataverse and another dataverse. Only accessible to sup
     curl -H "X-Dataverse-key: $API_TOKEN" -X DELETE http://$SERVER/api/dataverses/$linked-dataverse-alias/deleteLink/$linking-dataverse-alias
 
 Add Dataverse RoleAssignments to Child Dataverses
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Recursively assigns the users and groups having a role(s),that are in the set configured to be inheritable via the :InheritParentRoleAssignments setting, on a specified dataverse to have the same role assignments on all of the dataverses that have been created within it. The response indicates success or failure and lists the individuals/groups and dataverses involved in the update. Only accessible to superusers. ::
  

doc/sphinx-guides/source/api/apps.rst

@@ -53,6 +53,14 @@ metrics.dataverse.org_ aggregates metrics across multiple Dataverse installation
 Java
 ----
 
+DVUploader
+~~~~~~~~~~~~~~~~~~~~~
+
+The open-source DVUploader tool is a stand-alone command-line Java application that uses the Dataverse API to upload files to a specified Dataset. Files can be specified by name, or the DVUploader can upload all files in a directory or recursively from a directory tree. The DVUploader can also verify that uploaded files match their local sources by comparing the local and remote fixity checksums. Source code, release 1.0.0- jar file, and documentation are available on GitHub. DVUploader's creation was supported by the Texas Digital Library.
+
+https://github.com/IQSS/dataverse-uploader
+
+
 Dataverse for Android
 ~~~~~~~~~~~~~~~~~~~~~
 

doc/sphinx-guides/source/developers/intro.rst

@@ -55,6 +55,7 @@ As a developer, you also may be interested in these projects related to Datavers
 
 - External Tools - add additional features to Dataverse: See the :doc:`/installation/external-tools` section of the Installation Guide.
 - Dataverse API client libraries - use Dataverse APIs from various languages: :doc:`/api/client-libraries`
+- DVUploader - a stand-alone command-line Java application that uses the Dataverse API to support upload of files from local disk to a Dataset: https://github.com/IQSS/dataverse-uploader 
 - Miniverse - expose metrics from a Dataverse database: https://github.com/IQSS/miniverse
 - Configuration management scripts - Ansible, Puppet, etc.: See "Advanced Installation" in the :doc:`/installation/prep` section of the Installation Guide.
 - :doc:`/developers/unf/index` (Java) -  a Universal Numerical Fingerprint: https://github.com/IQSS/UNF

doc/sphinx-guides/source/user/dataset-management.rst

@@ -104,6 +104,23 @@ An rsync-enabled Dataverse installation has a file upload process that differs f
 
 **Note:** A dataset can only hold one data package. If you need to replace the data package in your dataset, contact Support.
 
+Command-line DVUploader
+-----------------------
+
+The open-source DVUploader tool is a stand-alone command-line Java application that uses the Dataverse API to upload files to a specified Dataset. Since it can be installed by users, and requires no server-side configuration, it can be used with any Dataverse installation. It is intended as an alternative to uploading files through the Dataverse web interface in situations where the web interface is inconvenient due to the number of files or file locations (spread across multiple directories, mixed with files that have already been uploaded or file types that should be excluded) or the need to automate uploads. Since it uses the Dataverse API, transfers are limited in the same ways as HTTP uploads through the Dataverse web interface in terms of size and performance. The DVUploader logs its activity and can be killed and restarted as desired. If stopped and resumed, it will continue processing from where it left off.
+
+Usage
+~~~~~
+
+The DVUploader is open source and is available as source, as a Java jar, and with documentation at https://github.com/IQSS/dataverse-uploader. The DVUploader requires Java 1.8+. Users will need to install Java if they don't already have it and then download the DVUploader-v1.0.0.jar file. Users will need to know the URL of the Dataverse server, the DOI of their existing Dataverse Dataset, and have generated a Dataverse API Key (an option in the user's profile menu). 
+
+Basic usage is to run the command: ::
+
+    java -jar DVUploader-v1.0.0.jar -server=<Dataverse server URL> -did=<Dataset DOI> -key=<User's API Key> <file or directory list>
+
+Additional command line arguments are available to make the DVUploader list what it would do without uploading, limit the number of files it uploads, recurse through sub-directories, verify fixity, exclude files with specific extensions or name patterns, and/or wait longer than 60 seconds for any Dataverse ingest lock to clear (e.g. while the previously uploaded file is processed, as discussed in the File Handling section below). 
+
+DVUploader is a community-developed tool, and its creation was primarily supported by the Texas Digital Library. Further information and support for DVUploader can be sought at `the project's GitHub repository <https://github.com/IQSS/dataverse-uploader>`_ . 
 
 File Handling
 =============