overall doc review #210

PipKat · 2025-04-24T13:00:06Z

Performing overall doc review post-release.

I can't find the source for the index page of the "API reference" section to edit it to reflect the text we currently use. Where is it coming from? Also, there are a lot of descriptions missing from this section, especially in regard to attribute tables.

I moved the default to where the data type of a parameter is defined. However, the format isn't quite what usually shows. The default and often the value are in bold.

codecov-commenter · 2025-04-24T13:11:10Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.98%. Comparing base (6323797) to head (c1ab437).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #210      +/-   ##
==========================================
- Coverage   84.99%   82.98%   -2.02%     
==========================================
  Files          19       19              
  Lines        1193     1193              
==========================================
- Hits         1014      990      -24     
- Misses        179      203      +24

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

PipKat · 2025-04-24T13:41:46Z

examples/basic/00_file_operations_client.py

-File Operations
-===============
+===================
+Run file operations


I put the 00 and 01 prefixes in the file names of the examples in this section in an attempt to reorder them so that the "Run file operations" was first and "Run file operations asynchronously" was second. However, this did not reorder them. If I was correct in assuming that this would be the preferred order, please make whatever changes are necessary to accomplish this.

PipKat · 2025-04-24T13:46:37Z

examples/basic/01_async_data_transfer_client.py

+    await client.start()
+
+    ########################################
+    # Create a AsyncDataTransferApi instance


Did you intend the use of this ReStructuredText formatting here? In the rendered doc, it looks odd within the code block.

PipKat · 2025-04-24T13:51:49Z

examples/permissions/set_permissions_example.py

@@ -27,7 +27,7 @@
 Set and query permissions
 =========================

-Example script to set and query permissions on files and


This ReStructuredText formatting within the script also looks odd in the rendered documentation and perhaps should be changed:
###################################
# Create a DataTransferApi instance
# =================================

PipKat · 2025-04-24T13:53:44Z

examples/startup/data_transfer_runner.py

@@ -62,7 +62,7 @@ def main(
    assert user_token is not None

    ##########################
-    # Create a Client instance
+    # Create a client instance


This ReStructuredText formatting within the script also looks odd in the rendered documentation and perhaps should be changed.

PipKat · 2025-04-24T13:57:42Z

examples/transfer_files/transfer_files.py

@@ -49,8 +47,8 @@
 from typing_extensions import Annotated

 ###################################################
-# Necessary imports
-# =================
+# Perform necessary imports


Given that this code block has a heading, put a heading before the preceding code block? This would allow the reader to use the right pane to jump to either of the two subheadings.

PipKat · 2025-04-24T13:58:16Z

examples/transfer_files/transfer_files.py

@@ -169,7 +167,7 @@ def main(

    log.info("Connecting to the data transfer service client..")
    ##############################
-    # Create a ``client`` instance
+    # Create a client instance


This ReStructuredText formatting within the script also looks odd in the rendered documentation and perhaps should be changed.

PipKat · 2025-04-24T15:20:48Z

doc/source/contribute.rst

@@ -83,7 +83,7 @@ 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`_.


We should respect the capitalization that the creators use for the name.

PipKat · 2025-04-24T16:58:34Z

examples/permissions/set_permissions_example.py

@@ -27,7 +27,7 @@
 Set and query permissions
 =========================

-Example script to set and query permissions on files and
+This example script sets and queries permissions on files and


It seems odd to me that so many sections only have one example. Is this because more are to be added soon? If not, should we come up with ways of grouping them?

PipKat · 2025-04-24T17:41:47Z

src/ansys/hps/data_transfer/client/utils/otel_config.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.

-"""This module provides utilities for configuring OpenTelemetry (Otel) settings for the Ansys HPS Data Transfer Client.
+"""Provides utilities for configuring OpenTelemetry (Otel) settings for the Ansys HPS Data Transfer Client.


In the doc, the "Module detail" section isn't formatted correctly.

PipKat · 2025-04-24T17:46:19Z

src/ansys/hps/data_transfer/client/authenticate.py

-    verify: Union[bool, str], optional
+    timeout : float, default: 10.0
+        Timeout in seconds.
+    verify: Union[bool, str]


The Returns section for this class is formatted oddly in the documentation. I removed the colon after Returns but pre-commit "fixed" it since it said the removal was an error. At the bottom of this page in the doc, there is also a "log" entry that appears to be a link but doesn't do anything. I'm not sure where that is coming from.

PipKat · 2025-04-24T17:56:17Z

src/ansys/hps/data_transfer/client/client.py

@@ -535,7 +535,7 @@ async def _monitor(self):


 class Client(ClientBase):
-    """Provide the Python client to the HPS data transfer APIs.
+    """Provides the Python client to the HPS data transfer APIs.


The example for this class isn't formatted to render properly in the doc.

PipKat · 2025-04-24T17:59:34Z

src/ansys/hps/data_transfer/client/exceptions.py

@@ -19,7 +19,7 @@
 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
-"""This module provides the base class for all client and server HPS-related errors."""
+"""Provides the base class for all client and server HPS-related errors."""


In the Summary for the exceptions, four of them have the same description: "Provides client-side related errors." Is this what you want?

overall doc review

86f3c13

PipKat requested review from nezgrath, ojkoenig and FedericoNegri as code owners April 24, 2025 13:00

github-actions bot added the documentation Improvements or additions to documentation label Apr 24, 2025

PipKat commented Apr 24, 2025

View reviewed changes

FedericoNegri requested a review from saimanikant April 24, 2025 15:00

PipKat commented Apr 24, 2025

View reviewed changes

PipKat added 2 commits April 24, 2025 11:34

Additional edits for cleanup and better consistency

66e4e59

Fix based on running pre-commit

ef6b8f6

PipKat commented Apr 24, 2025

View reviewed changes

PipKat added 2 commits April 24, 2025 14:00

Edits based on looking at HTML artifact

c57c1cd

Fix some lines that were too long

c1ab437

PipKat requested a review from AlejandroFernandezLuces April 24, 2025 18:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

overall doc review #210

overall doc review #210

PipKat commented Apr 24, 2025 •

edited

Loading

codecov-commenter commented Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025

PipKat Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025

PipKat Apr 24, 2025

PipKat Apr 24, 2025

PipKat Apr 24, 2025

PipKat Apr 24, 2025

PipKat Apr 24, 2025

PipKat Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025

PipKat Apr 24, 2025

overall doc review #210

Are you sure you want to change the base?

overall doc review #210

Conversation

PipKat commented Apr 24, 2025 • edited Loading

codecov-commenter commented Apr 24, 2025 • edited Loading

Codecov Report

PipKat Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PipKat Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PipKat Apr 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PipKat commented Apr 24, 2025 •

edited

Loading

codecov-commenter commented Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025 •

edited

Loading

PipKat Apr 24, 2025 •

edited

Loading