overall doc review

README.rst

@@ -34,28 +34,27 @@ PyHPS Data Transfer
 Overview
 --------
 
-Python client library for HPS Data Transfer Service
+PyHPS Data Transfer is a Python client library for the Ansys HPC Platform Services (HPS) data transfer service.
 
 .. contribute_start
 
 Installation
 ^^^^^^^^^^^^
-
-You can use `pip <https://pypi.org/project/pip/>`_ to install PyHPS Data Transfer.
+You can use `pip <https://pypi.org/project/pip/>`_ to install PyHPS Data Transfer in user mode:
 
 .. code:: bash
 
     pip install ansys-hps-data-transfer-client
 
-To install the latest development version, run these commands:
+To install the latest development version from the GitHub repository, run these commands:
 
 .. code:: bash
 
     git clone https://github.com/ansys/pyhps-data-transfer/
     cd pyhps-data-transfer
     pip install -e .
 
-For more information, see `Getting Started`_.
+For more information, see `Getting started`_.
 
 Basic usage
 ^^^^^^^^^^^

doc/source/contribute.rst

@@ -60,13 +60,13 @@ Installing PyHPS Data Transfer in developer mode allows you to modify and enhanc
       tox
 
 Test PyPyHPS Data Transfer
----------------------------------
+--------------------------
 
 PyHPS Data Transfer takes advantage of `tox`_. This tool allows you to automate common development
 tasks (similar to ``Makefile``), but it is oriented towards Python development.
 
-Using ``tox``
-^^^^^^^^^^^^^
+Use ``tox``
+^^^^^^^^^^^
 
 While ``Makefile`` has rules, ``tox`` has environments. In fact, ``tox``
 creates its own virtual environment so that anything being tested is isolated
@@ -79,16 +79,16 @@ The following environment commands are provided:
 - ``tox -e py-coverage``: Checks for unit testing and code coverage.
 - ``tox -e doc``: Checks for documentation building.
 
-Raw testing
-^^^^^^^^^^^
+Perform raw testing
+^^^^^^^^^^^^^^^^^^^
 
 If required, from the command line, you can call style commands like
-`ruff`_. You can also call unit testing commands like `pytest`_.
+`Ruff`_. You can also call unit testing commands like `pytest`_.
 However, running these commands do not guarantee that your project is being tested
 in an isolated environment, which is the reason why tools like ``tox`` exist.
 
-Code style
-----------
+Adhere to code style
+--------------------
 
 As indicated in `Coding style <https://dev.docs.pyansys.com/coding-style/index.html>`_
 in the *PyAnsys developer's guide*, PyHPS Data Transfer follows PEP8 guidelines. PyHPS Data Transfer
@@ -114,10 +114,10 @@ This way, it's not possible for you to push code that fails the style checks::
   Validate GitHub Workflows................................................Passed
   Add License Headers......................................................Passed
 
-Documentation
--------------
+Build documentation
+-------------------
 
-For building documentation, you can manually run these commands:
+To build documentation manually, run these commands:
 
 .. code:: bash
 
@@ -131,8 +131,8 @@ However, the recommended way of checking documentation integrity is to use
 
     tox -e doc && your_browser_name .tox/doc_out/index.html
 
-Distributing
-------------
+Distribute
+----------
 
 If you would like to create either source or wheel files, start by installing
 the building requirements and then executing the build module:
@@ -145,7 +145,7 @@ the building requirements and then executing the build module:
 
 
 .. LINKS AND REFERENCES
-.. _ruff: https://docs.astral.sh/ruff/
+.. _Ruff: https://docs.astral.sh/ruff/
 .. _pytest: https://docs.pytest.org/en/stable/
 .. _pip: https://pypi.org/project/pip/
 .. _pre-commit: https://pre-commit.com/

doc/source/getting_started/index.rst

@@ -4,7 +4,7 @@ Getting started
 ===============
 
 This section describes how to install PyHPS Data Transfer in user mode. If you are interested in contributing
-to PyHPS Data Transfer.
+to PyHPS Data Transfer, see :ref:`contribute` for information on installing in developer mode.
 
 Prerequisites
 -------------
@@ -18,16 +18,16 @@ You must have pip_ and Python 3.9, 3.10, 3.11, or 3.12 installed.
 
        python --version
 
-#. If you do not have a Python 3.x version installed, install the latest 3.x version from the
-   Python organization's `Downloads <https://python.org>`_ page.
+#. If a Python 3.x version is not available, install the latest 3.x version from the
+   Python organization's `Downloads <https://www.python.org/downloads/>`_ page.
 
 #. To see if you have ``pip`` installed, run this command:
 
    .. code::
 
        pip --version
 
-#. If you do not have ``pip`` installed, see `Installing Packages <https://packaging.python.org/tutorials/installing-packages/>`_
+#. If ``pip`` is not installed, see `Installing Packages <https://packaging.python.org/tutorials/installing-packages/>`_
    in the *Python Packaging User Guide*.
 
 #. To ensure that you have the latest version of ``pip``, run this command:
@@ -40,7 +40,7 @@ You must have pip_ and Python 3.9, 3.10, 3.11, or 3.12 installed.
 Installation
 ------------
 
-To install ansys-hps-data-transfer-client in user mode, run this command:
+To install PyHPS Data Transfer in user mode, run this command:
 
 .. code:: bash
 

doc/source/index.rst

@@ -3,13 +3,16 @@ PyHPS Data Transfer documentation |version|
 
 Ansys HPC Platform Services (HPS) is a set of technology components designed to help you
 manage the execution of simulations while making use of your full range of computing assets.
-Data transfer service is a modular, plugin-based solution, which helps to solve complex data transfer problems for HPS.
-PyHPS Data Transfer brings HPS data transfer client to your Python app.
-Wrapping around data transfer client REST APIs, PyHPS Data Transfer allows you to:
+PyHPS Data Transfer is a Python client library for the HPS data transfer service. This
+modular, plugin-based solution wraps around data transfer client REST APIs to help solve
+complex data transfer problems for HPS.
+
+With PyHPS Data Transfer, you can perform these operations:
 
 * Create and list files.
 * Copy files.
 * Set and view permissions.
+* Delete files.
 
 
 .. grid:: 1 2 2 2
@@ -20,7 +23,8 @@ Wrapping around data transfer client REST APIs, PyHPS Data Transfer allows you t
             :link: getting_started/index
             :link-type: doc
 
-            Learn how to install and start using PyHPS Data Transfer.
+            Learn how to install PyHPS Data Transfer in user mode and
+            quickly start using it.
 
         .. grid-item-card:: User guide :fa:`book-open-reader`
             :padding: 2 2 2 2

doc/source/user_guide/index.rst

@@ -3,19 +3,18 @@
 User guide
 ==========
 
-This section walks you through the basics of how to interact with the Data transfer client service.
+This section explains how to interact with PyHPS Data Transfer.
 
-To reproduce the code samples provided in this section, you must have these
-prerequisites:
+To run the code samples in this section, you must have these prerequisites:
 
 - A running Ansys HPS installation. For more information, see the
-  `Ansys HPC Platform Services Guide <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/prod_page.html?pn=Ansys%20HPC%20Platform%20Services&pid=HpcPlatformServices&lang=en>`_
+  `Ansys HPC Platform Services Deployment Guide <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/prod_page.html?pn=Ansys%20HPC%20Platform%20Services&pid=HpcPlatformServices&lang=en>`_
   in the Ansys Help.
 - A Python shell with PyHPS Data Transfer installed. For more information, see :ref:`getting_started`.
 
 ..
-   This toctreemust be a top level index to get it to show up in
-   pydata_sphinx_theme
+   This toctree must be a top-level index to display in
+   pydata_sphinx_theme.
 
 .. toctree::
    :maxdepth: 1
@@ -25,10 +24,11 @@ prerequisites:
    run_async
 
 
-Connect to a data transfer service
-----------------------------------
+Connect to a data transfer service client
+-----------------------------------------
 
-You start by connecting to the data transfer service running on the localhost with the default username and password by first requesting access token:
+The data transfer service runs on the localhost with the default username and password. Before you can connect to
+a data transfer service client, you must request the access token:
 
 .. code-block:: python
 
@@ -40,8 +40,7 @@ You start by connecting to the data transfer service running on the localhost wi
     token = authenticate(username="repadmin", password="repadmin", verify=False, url=auth_url)
     token = token.get("access_token", None)
 
-
-Using the token, connect to the data transfer service client:
+You can now use this access token to make a connection:
 
 .. code-block:: python
 
@@ -57,7 +56,7 @@ Using the token, connect to the data transfer service client:
     api = DataTransferApi(client)
     api.status(wait=True)
 
-Once connected, you can query storages available:
+Use this code to query available storages:
 
 .. code-block:: python
 
@@ -67,33 +66,37 @@ Once connected, you can query storages available:
 Create a directory
 ------------------
 
-To create a directory:
+Create a directory in a storage location:
 
 .. code-block:: python
 
     base_dir = "basic-example"
-    mkdir_op = api.mkdir([StoragePath(path=f"{base_dir}")])
-    api.wait_for([mkdir_op.id])
+            mkdir_op = api.mkdir([StoragePath(path=f"{base_dir}")])
+        api.wait_for([mkdir_op.id])
+
+Copy files
+----------
+
+When copying files, the ``local_path`` attribute is the path to the
+files or directory to copy. The ``remote_path`` attribute is the path to
+the remote directory to copy files to.
+
+The paths used by the data transfer components follow this format:
 
-Copying files
-----------------
+``[remote or keyword]:/path/to/file.txt``
 
-In the following code block, local_path is path to the files or directory to transfer.
-remote_path is path to the remote directory to transfer files to.
-The paths used by the data transfer components look like
+The ``[remote or keyword]`` part can be the name of a specific remote, ``any``, or be left empty. Specifying the name of a remote performs the given command only against it. Specifying ``any`` or leaving it empty runs the standard logic of the system and works through remotes in priority order.
 
-[remote or keyword]:/path/to/file.txt
-The [remote or keyword] part can be either the name of a specific remote, "any", or empty. Empty and "any" amount to the same - running the standard logic of the system, working through remotes in priority order. Specifying the name of a remote performs the given command only against it.
+If an operation should be performed against a local file or directory, remove the first part, including the colon.
 
-If an operation should be performed against a local file or directory, the first part, including the colon, should be removed.
+**Examples:**
 
-Examples:
-any:mnt/test/path.txt - a file in any of the available remotes
-:mnt/test/path.txt - shorthand for any:[]
-s3test:some/test/path.txt - a file in storage called "s3test"
-another/test/path.txt - a local path
+- ``any:mnt/test/path.txt``: A file in any of the available remotes.
+- ``:mnt/test/path.txt``: Shorthand for any (``[]``).
+- ``s3test:some/test/path.txt``: A file named ``s3test`` in a storage location.
+- ``another/test/path.txt``: A local path.
 
-To copy files:
+Copy files between storage locations:
 
 .. code-block:: python
 
@@ -106,10 +109,10 @@ To copy files:
     op = api.wait_for([op.id])
     log.info(f"Operation {op[0].state}")
 
-Listing files
-----------------
+List files
+----------
 
-To list files in a set path (base_dir in the following code block):
+List files in a specified directory:
 
 .. code-block:: python
 
@@ -118,11 +121,10 @@ To list files in a set path (base_dir in the following code block):
     log.info(f"Operation {op[0].state}")
     log.info(f"Files in {base_dir}: {op[0].result}")
 
+Get metadata
+------------
 
-Getting metadata
-----------------
-
-To get metadata of files:
+Get the metadata of a file in a specified directory:
 
 .. code-block:: python
 
@@ -131,23 +133,21 @@ To get metadata of files:
     md = op[0].result[f"{base_dir}/2.txt"]
     log.info(f"Metadata for {base_dir}/2.txt: {md}")
 
-Removing files
-----------------
+Remove files
+------------
 
-To get remove files:
+Remove files in a specified directory:
 
 .. code-block:: python
 
     op = api.rmdir([StoragePath(path=base_dir)])
     op = api.wait_for([op.id])
 
 Stop client
-----------------
+-----------
 
-To stop client:
+Stop the client:
 
 .. code-block:: python
 
     client.stop()
-
-