Overall doc edit for public release (#278)

Co-authored-by: Kerry McAdams <[email protected]>
Co-authored-by: Kerry McAdams <[email protected]>

README.rst

@@ -31,159 +31,60 @@ PyHPS
    :alt: Black
 
 
-A Python client library for the Ansys HPC Platform Services.
-
-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/
+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 Ansys HPS REST APIs, PyHPS
+allows you to:
+
+* Create projects and modify existing ones.
+* Monitor and manage jobs.
+* Run your own design exploration algorithms.
+* Retrieve simulation results.
+
+Documentation and issues
+------------------------
+
+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 contains these sections:
+
+- `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 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 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.
+
+On the `PyHPS Issues <https://github.com/ansys-internal/pyhps/issues>` page, you can
+create issues to report bugs and request new features. 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]>`_.
+
+License
+-------
+
+PyHPS is licensed under the MIT license.
+
+PyHPS makes no commercial claim over Ansys whatsoever. This library extends the
+functionality of Ansys HPC Platform Services by adding a Python interface to it
+without changing the core behavior or license of the original software. The use
+of PyHPS requires a legally licensed local copy of AEDT.
+
+To get a copy of AEDT, see the `Ansys HPC Platform Services Guide <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/hpcplat/v000/en/rep_ug/rep_ug.html>`_`
+in the Ansys Help.

ansys/hps/client/__version__.py

@@ -27,5 +27,5 @@
 __url__ = "https://github.com/ansys-internal/pyhps"
 
 # this is only a convenience to default the version
-# of Ansys simulation applications in pyhps examples
+# of Ansys simulation applications in PyHPS examples
 __ansys_apps_version__ = "2024 R1"

ansys/hps/client/auth/api/auth_api.py

@@ -30,21 +30,21 @@
 
 
 class AuthApi:
-    """A python interface to the Authorization Service API.
+    """Provides the Python interface to the Authorization Service API.
 
-    Admin users with the Keycloak "manage-users" role can create new
-    users as well as modify or delete existing ones. Other users are only allowed
+    Admin users with the Keycloak "manage-users" role can create
+    users as well as modify or delete existing users. Non-admin users are only allowed
     to query the list of existing users.
 
     Parameters
     ----------
     client : Client
-        An HPS client object.
+        HPS client object.
 
     Examples
     --------
 
-    Get users whose first name contains "john":
+    Get users whose first name contains ``john``.
 
     >>> from ansys.hps.client import Client
     >>> from ansys.hps.client.auth import AuthApi, User
@@ -54,7 +54,7 @@ class AuthApi:
     >>> auth_api = AuthApi(cl)
     >>> users = auth_api.get_users(firstName="john", exact=False)
 
-    Create a new user:
+    Create a user:
 
     >>> new_user = User(
     ...     username="new_user",
@@ -72,44 +72,43 @@ def __init__(self, client):
 
     @property
     def url(self):
-        """Returns the API url"""
+        """API URL."""
         return f"{self.client.url}/auth/"
 
     @property
     def keycloak_admin_client(self) -> KeycloakAdmin:
-        """Returns an authenticated client for the Keycloak Admin API"""
+        """Authenticated client for the Keycloak Admin API."""
         return _admin_client(self.client)
 
     def get_users(self, as_objects=True, **query_params) -> List[User]:
-        """Return users, filtered according to query parameters
+        """Get users, filtered according to query parameters.
 
         Examples of query parameters are:
-            - `username`
-            - `firstName`
-            - `lastName`
-            - `exact`
+        - ``username``
+        - ``firstName``
+        - ``lastName``
+        - ``exact``
 
-        Pagination is also supported using the `first` and `max` parameters.
+        Pagination is also supported using the ``first`` and ``max`` parameters.
 
-        For the complete list of supported query parameters, please
-        refer to the Keycloak API documentation.
+        For a list of supported query parameters, see the Keycloak API documentation.
         """
         return get_users(self.keycloak_admin_client, as_objects=as_objects, **query_params)
 
     def get_user(self, id: str) -> User:
-        """Returns the user representation for a given user id."""
+        """Get the user representation for a given user ID."""
         return get_user(self.keycloak_admin_client, id)
 
     def get_user_groups(self, id: str) -> List[str]:
-        """Get name of groups the user belongs to"""
+        """Get the groups that the user belongs to."""
         return [g["name"] for g in self.keycloak_admin_client.get_user_groups(id)]
 
     def get_user_realm_roles(self, id: str) -> List[str]:
-        """Get name of realm roles for a user"""
+        """Get the realm roles for the user."""
         return [r["name"] for r in self.keycloak_admin_client.get_realm_roles_of_user(id)]
 
     def user_is_admin(self, id: str) -> bool:
-        """Check whether the user is system admin"""
+        """Determine if the user is a system administrator."""
 
         from ansys.hps.client.jms import JmsApi
 
@@ -131,28 +130,36 @@ def user_is_admin(self, id: str) -> bool:
         return False
 
     def create_user(self, user: User, as_objects=True) -> User:
-        """Create a new user.
-
-        Args:
-            user (:class:`ansys.hps.client.auth.User`): A User object. Defaults to None.
-            as_objects (bool, optional): Defaults to True.
+        """Create a user.
+
+        Parameters
+        ----------
+        user : :class:`ansys.hps.client.auth.User`
+            User object. The default is ``None``.
+        as_objects : bool, optional
+            The default is ``True``.
         """
         return create_user(self.keycloak_admin_client, user, as_objects=as_objects)
 
     def update_user(self, user: User, as_objects=True) -> User:
         """Modify an existing user.
 
-        Args:
-            user (:class:`ansys.hps.client.auth.User`): A User object. Defaults to None.
-            as_objects (bool, optional): Defaults to True.
+        Parameters
+        ----------
+        user : :class:`ansys.hps.client.auth.User`
+            User object. The default is ``None``.
+        as_objects : bool, optional
+            The default is  ``True``.
         """
         return update_user(self.keycloak_admin_client, user, as_objects=as_objects)
 
     def delete_user(self, user: User) -> None:
         """Delete an existing user.
 
-        Args:
-            user (:class:`ansys.hps.client.auth.User`): A User object. Defaults to None.
+        Parameters
+        ----------
+        user : :class:`ansys.hps.client.auth.User`
+            User object. The default is ``None``.
         """
         return self.keycloak_admin_client.delete_user(user.id)