Second-pass edits passed on doc rendering in HTML artifact

README.rst

@@ -35,180 +35,35 @@ PyHPS is a Python client library for Ansys HPC Platform Services (HPS), which 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.
 
-PyHPS brings Ansys HPS to your Python app. Wrapping around the HPS REST APIs, PyHPS allows you to:
+PyHPS brings Ansys HPS to your Python app. Wrapping around Ansys HPS REST APIs, PyHPS
+allows you to:
 
 * Create projects and modify existing ones.
 * Monitor and manage jobs.
-* Run your own design exploration algorithms .
+* Run your own design exploration algorithms.
 * Retrieve simulation results.
 
 Documentation
 -------------
+
+Documentation for the latest stable release of PyHPS is hosted at
+`PyHPS documentation <https://rep.docs.pyansys.com/dev/>`_.
+
+In the upper right corner of the documentation's title bar, there is an option
+for switching from viewing the documentation for the latest stable release
+to viewing the documentation for the development version or previously
+released versions.
+
 The `PyHPS documentation <https://rep.docs.pyansys.com/>`_ contains these sections:
 
-- `Getting started <https://rep.docs.pyansys.com/dev/getting-started/index.html>`_: Explains
+- `Getting started <https://rep.docs.pyansys.com/dev/getting_started/index.html>`_: Explains
   how to install PyHPS in user mode.
-- `User guide <https://rep.docs.pyansys.com/dev/user_guide/index.html>`_: Describes how to use
-  PyHPS to interact with Ansys HPS.
-- `Examples <https://rep.docs.pyansys.com/dev/examples/index.html>`: Provides examples of how
-  to interact with a REP server in Python using PyHPS.
+- `User guide <https://rep.docs.pyansys.com/dev/user_guide/index.html>`_: Describes the basics
+  of how to use PyHPS to interact with Ansys HPS.
+- `Examples <https://rep.docs.pyansys.com/dev/examples/index.html>`_: Provides examples of how
+  to interact with a Remote Execution Platform (REP) server in Python using PyHPS.
 - `API reference <https://rep.docs.pyansys.com/dev/api/index.html>`_: Describes PyHPS functions,
-  classes, methods, and their parameters and return values so that you understand how to interact
-  with them programmatically
+  classes, methods, and their parameters and return values so that you can understand how to
+  interact with them programmatically
 - `Contribute <https://rep.docs.pyansys.com/dev/contribute.html>`: Provides information on
   how to install PyHPS in developer mode and make contributions to the codebase.
-
-How to install
---------------
-
-In order to install PyHPS, make sure you
-have the latest version of `pip`_. To do so, run:
-
-.. code:: bash
-
-    python -m pip install -U pip
-
-Then, as long as PyHPS is a private pyAnsys module not published to pypi yet, you can execute:
-
-.. code:: bash
-
-    python -m pip install git+https://github.com/pyansys/pyhps
-
-.. TODO: Enable this once pyhps is published:  python -m pip install ansys-pyhps
-
-Contribute
-----------
-
-Before contributing to the project, ensure that you are thoroughly
-familiar with the `PyAnsys Developer's guide`_. You will 
-need to follow these steps:
-
-#. Clone this repository:
-
-    .. code:: bash
-
-        git clone https://github.com/pyansys/pyhps
-        cd pyhps
-
-#. Create a new Python environment and activate it:
-
-    .. code:: bash
-
-        # Create a virtual environment
-        python -m venv .venv
-
-        # Activate it in a POSIX system
-        source .venv/bin/activate
-
-        # Activate it in Windows CMD environment
-        .venv\Scripts\activate.bat
-
-        # Activate it in Windows Powershell
-        .venv\Scripts\Activate.ps1
-
-#. Make sure you have the latest required build system and doc, testing, and CI tools:
-
-    .. code:: bash
-
-        python -m pip install -U pip setuptools tox
-        python -m pip install -r requirements/requirements_build.txt
-        python -m pip install -r requirements/requirements_doc.txt
-        python -m pip install -r requirements/requirements_tests.txt
-
-
-#. Install the project in editable mode:
-
-    .. code:: bash
-    
-        python -m pip install --editable .
-
-How to testing
---------------
-
-This project takes advantage of `tox`_. This tool allows to automate common
-development tasks (similar to Makefile) but it is oriented towards Python
-development. 
-
-Using tox
-^^^^^^^^^
-
-As Makefile has rules, `tox`_ has environments. In fact, the tool creates its
-own virtual environment so anything being tested is isolated from the project in
-order to guarantee project's integrity. The following environments commands are provided:
-
-- **tox -e style**: will check for coding style quality.
-- **tox -e py**: checks for unit tests.
-- **tox -e py-coverage**: checks for unit testing and code coverage.
-- **tox -e doc**: checks for documentation building process.
-
-
-Raw testing
-^^^^^^^^^^^
-
-If required, you can always call the style commands (`black`_, `isort`_,
-`flake8`_...) or unit testing ones (`pytest`_) from the command line. However,
-this does not guarantee that your project is being tested in an isolated
-environment, which is the reason why tools like `tox`_ exist.
-
-
-A note on pre-commit
-^^^^^^^^^^^^^^^^^^^^
-
-The style checks take advantage of `pre-commit`_. Developers are not forced but
-encouraged to install this tool via:
-
-.. code:: bash
-
-    python -m pip install pre-commit && pre-commit install
-
-
-Documentation
--------------
-
-For building documentation, you can manually run:
-
-.. code:: bash
-
-    python archive_examples.py
-    python -m sphinx -b html doc/source build/sphinx/html
-
-The recommended way of checking documentation integrity is using:
-
-.. code:: bash
-
-    tox -e doc && your_browser_name .tox/doc_out/index.html
-
-
-Distributing
-------------
-
-If you would like to create either source or wheel files, start by installing
-the building requirements and then executing the build module:
-
-.. code:: bash
-
-    python -m pip install -r requirements/requirements_build.txt
-    python -m build
-    python -m twine check dist/*
-
-How to generate/update RMS models
----------------------------------
-
-
-To generate RMS Pydantic models, first download the RMS openapi spec and save it as `rms_openapi.json` at the root of the repository.
-Then, run the datamodel generator:
-
-.. code:: bash
-    
-    datamodel-codegen --input .\rms_openapi.json --input-file-type openapi --output ansys/hps/client/rms/models.py --output-model-type pydantic_v2.BaseModel
-
-.. LINKS AND REFERENCES
-.. _black: https://github.com/psf/black
-.. _flake8: https://flake8.pycqa.org/en/latest/
-.. _isort: https://github.com/PyCQA/isort
-.. _pip: https://pypi.org/project/pip/
-.. _pre-commit: https://pre-commit.com/
-.. _PyAnsys Developer's guide: https://dev.docs.pyansys.com/
-.. _pytest: https://docs.pytest.org/en/stable/
-.. _Sphinx: https://www.sphinx-doc.org/en/master/
-.. _tox: https://tox.wiki/

doc/source/contribute.rst

@@ -15,17 +15,15 @@ The following contribution information is specific to PyHPS.
 Install in developer mode
 -------------------------
 
-Installing PyHPS in developer mode allows you to modify the source and enhance it.
+Installing PyHPS in developer mode allows you to modify and enhance the source:
 
-To install PyHPS in developer mode, perform these steps:
-
-#. Clone the ``pyhps`` repository:
+#. Clone the repository:
 
    .. code:: bash
 
       git clone https://github.com/pyansys/pyhps
 
-#. Access the ``pyhps`` directory where the repository has been cloned:
+#. Access the directory where you have cloned the repository:
 
    .. code:: bash
 
@@ -41,7 +39,7 @@ To install PyHPS in developer mode, perform these steps:
       # Activate it in a POSIX system
       source .venv/bin/activate
 
-      # Activate it in Windows CMD environment
+      # Activate it in a Windows CMD environment
       .venv\Scripts\activate.bat
 
       # Activate it in Windows Powershell
@@ -65,15 +63,14 @@ To install PyHPS in developer mode, perform these steps:
 
 #. Verify your development installation:
 
-    .. code:: bash
-
-        tox
+   .. code:: bash
 
+      tox
 
 Test PyHPS
 ----------
 
-PyHPS takes advantage of `tox`_. This tool automates common development
+PyHPS takes advantage of `tox`_. This tool allows you to automates common development
 tasks (similar to ``Makefile``), but it is oriented towards Python development.
 
 Using ``tox``
@@ -88,22 +85,22 @@ The following environment commands are provided:
 - ``tox -e style``: Checks for coding style quality.
 - ``tox -e py``: Checks for unit tests.
 - ``tox -e py-coverage``: Checks for unit testing and code coverage.
-- ``tox -e doc``: Checks for the documentation-building process.
-
+- ``tox -e doc``: Checks for documentation building.
 
 Raw testing
 ^^^^^^^^^^^
 
 If required, from the command line, you can call style commands like
-`black`_, `isort`_, and `flake8`_. You can also call unit testing commands like `PyTest`_.
+`Black`_, `isort`_, and `Flake8`_. 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
 ----------
+
 As indicated in `Coding style <https://dev.docs.pyansys.com/coding-style/index.html>`_
 in the *PyAnsys developer's guide*, PyHPS follows PEP8 guidelines. PyHPS
-implements `pre-commit <https://pre-commit.com/>`_ for style checking.
+implements `pre-commit`_ for style checking.
 
 To ensure your code meets minimum code styling standards, run these commands::
 
@@ -156,9 +153,9 @@ the building requirements and then executing the build module:
 Generate or update RMS models
 -----------------------------
 
-To generate RMS Pydantic models, first download the RMS OpenAPI specification and save it as
-``rms_openapi.json`` in the root of the repository. Then, run the data model generator
-with this command:
+To generate Resource Management Service (RMS) pydantic models, first download the RMS OpenAPI
+specification and save it as ``rms_openapi.json`` in the root of the repository. Then, run the
+data model generator with this command:
 
 .. code:: bash
 
@@ -167,33 +164,22 @@ with this command:
 Post issues
 -----------
 Use the `PyHPS Issues <https://github.com/ansys-internal/pyhps/issues>`_
-page to submit questions, report bugs, and request new features. When possible,
-use these templates:
-
-* Bug report
-* Feature request
+page to report bugs and request new features. When possible, use the issue
+templates provided. If your issue does not fit into one of these templates,
+click the link for opening a blank issue.
 
-If your issue does not fit into one of these template categories, create your own issue.
+On the `PyHPS Discussions <https://github.com/ansys-internal/pyhps/discussions>`_ page
+or the `Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
+you can post questions, share ideas, and get community feedback.
 
 To reach the project support team, email `[email protected] <[email protected]>`_.
 
-
-View documentation
-------------------
-Documentation for the latest stable release of PyHPS is hosted at
-`PyHPS documentation <https://rep.docs.pyansys.com/dev/>`_.
-
-In the upper right corner of the documentation's title bar, there is an option
-for switching from viewing the documentation for the latest stable release
-to viewing the documentation for the development version or previously
-released versions.
-
 .. LINKS AND REFERENCES
-.. _black: https://github.com/psf/black
-.. _flake8: https://flake8.pycqa.org/en/latest/
+.. _Black: https://github.com/psf/black
 .. _isort: https://github.com/PyCQA/isort
+.. _Flake8: https://flake8.pycqa.org/en/latest/
+.. _pytest: https://docs.pytest.org/en/stable/
 .. _pip: https://pypi.org/project/pip/
 .. _pre-commit: https://pre-commit.com/
-.. _pytest: https://docs.pytest.org/en/stable/
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _tox: https://tox.wiki/

doc/source/examples/ex_cfx_static_mixer.rst

@@ -8,9 +8,9 @@ This example shows how to submit a CFX static mixer model for solving on Ansys H
 .. only:: builder_html
 
      You can download the :download:`ZIP file <../../../build/cfx_static_mixer.zip>` for
-     the CFX static mixer example and use a utility such as 7Zip to extract the files.
+     the CFX static mixer example and use a tool such as 7Zip to extract the files.
 
-Here is the ``project_setup.py`` file for this example:
+Here is the ``project_setup.py`` script for this example:
 
 .. literalinclude:: ../../../examples/cfx_static_mixer/project_setup.py
     :language: python

doc/source/examples/ex_fluent_2d_heat_exchanger.rst

@@ -8,9 +8,9 @@ This example shows how to submit a simple Fluent solve job to Ansys HPS. The mod
 .. only:: builder_html
 
      You can download the  :download:`ZIP file <../../../build/fluent_2d_heat_exchanger.zip>` for the Fluent 2D heat
-     exchanger example and use a utility such as 7Zip to extract the files.
+     exchanger example and use a tool such as 7Zip to extract the files.
 
-Here is the ``project_setup.py`` file for this example:
+Here is the ``project_setup.py`` script for this example:
 
 .. literalinclude:: ../../../examples/fluent_2d_heat_exchanger/project_setup.py
     :language: python

doc/source/examples/ex_fluent_nozzle.rst

@@ -8,9 +8,9 @@ This example shows how to submit a Fluent nozzle model for solving on REP.
 .. only:: builder_html
 
      You can download the :download:`ZIP file <../../../build/fluent_nozzle.zip>` for the
-     Fluent nozzle example and use a utility such as 7Zip to extract the files.
+     Fluent nozzle example and use a tool such as 7Zip to extract the files.
 
-Here is the ``project_setup.py`` file for this example:
+Here is the ``project_setup.py`` script for this example:
 
 
 .. literalinclude:: ../../../examples/fluent_nozzle/project_setup.py

doc/source/examples/ex_lsdyna_job.rst

@@ -31,9 +31,9 @@ The job consists of two tasks:
 .. only:: builder_html
 
      You can dowlonad the :download:`ZIP file <../../../build/lsdyna_cylinder_plate.zip>` for
-     the LS-DYNA job submission example and use a utility such as 7Zip to extract the files.
+     the LS-DYNA job submission example and use a tool such as 7Zip to extract the files.
 
-Here is the ``project_setup.py`` file for this example:
+Here is the ``project_setup.py`` script for this example:
 
 .. literalinclude:: ../../../examples/lsdyna_cylinder_plate/lsdyna_job.py
     :language: python

doc/source/examples/ex_mapdl_linked_analyses.rst

@@ -26,7 +26,7 @@ In both cases, output files from upstream tasks are used as inputs of downstream
 .. only:: builder_html
 
      You can download the :download:`ZIP file <../../../build/mapdl_linked_analyses.zip>` for the
-     MAPDL linked analyses example and use a utility such as 7Zip to extract the files.
+     MAPDL linked analyses example and use a tool such as 7Zip to extract the files.
 
 Here is the ``project_setup.py`` file for this project:.
 

doc/source/examples/ex_mapdl_tire_performance.rst

@@ -11,7 +11,7 @@ while the job is running.
 .. only:: builder_html
 
      You can download the :download:`ZIP file <../../../build/mapdl_tyre_performance.zip>`
-     for the MAPDL tire performance example and use a utility such as 7Zip to extract the files.
+     for the MAPDL tire performance example and use a tool such as 7Zip to extract the files.
 
 Here is the ``project_setup.py`` file for this project: