Quickstart documentation (#33)

* Quickstart documentation

README.rst

@@ -1,6 +1,143 @@
+=====
 PyPIM
 =====
 
-Python wrappers for the Product Instance Management API.
+PyPIM exposes a pythonic interface to communicate with the Product Instance
+Management API.
+
+What is the Product Instance Management API?
+============================================
+
+The Product Instance Management API is a gRPC API enabling library and
+application developers to start a product in a remote environment and
+communicate with its API.
+
+It is intended to be as simple as possible to be adaptable in a variety of
+network and software infrastructure. Using this API does not require any
+knowledge on this infrastructure, we want users to only know which product to
+start, and which API the product exposes. The API itself exposes very little
+feature and assumes that all the configuration is set on a server.
+
+It is not intended to manage stateless services, to be a job management system,
+or a fully featured service orchestration API, but rather to to expose a minimum
+feature set of such API for service oriented applications.
+
+Getting Started
+===============
+
+To use PyPIM, you need to have access to an exposition of the "Product
+Instance Management" API.
+
+.. note::
+    This is a work in progress and there is no public exposition or
+    distribution of an implementation yet.
+
+
+PyPIM itself is pure python and relies on `gRPC <https://grpc.io/>`_.
+
+Installation
+------------
+
+The ``ansys-platform-instancemanagement`` package is tested for Python 3.7 through
+Python 3.10 on Windows and Linux.
+
+.. code-block::
+
+    pip install ansys-platform-instancemanagement
+
+Usage
+-----
+
+PyPIM is a single module called ``ansys.platform.instancemanagement``, shortened
+to ``pypim``.
+
+Starting MAPDL and communicating with it:
+
+.. code-block::
+    
+    import ansys.platform.instancemanagement as pypim
+    from ansys.mapdl.core import Mapdl
+    
+    if pypim.is_configured():
+        pim=pypim.connect()
+        instance = pim.create_instance(product_name="mapdl", product_version="221")
+        instance.wait_for_ready()
+        channel = instance.build_grpc_channel(options=[("grpc.max_receive_message_length", 8*1024**2)])
+        mapdl = Mapdl(channel=channel)
+        mapdl.prep7()
+        ...
+        instance.delete()
+
+Developer Guide
+===============
+
+The general guidance appears in the `Contributing
+<https://dev.docs.pyansys.com/overview/contributing.html>`_ topic in the
+*PyAnsys Developer's Guide*.
+
+Cloning the PyPIM Repository
+----------------------------
+
+.. code-block::
+    
+    git clone https://github.com/pyansys/pypim.git
+    cd pypim/
+
+Running the tests
+-----------------
+
+The test automation relies on `tox
+<https://tox.wiki/en/latest/install.html#installation-with-pip>`_.
+
+They are entirely based on mocks and do not require any external software. Run
+the tests with:
+
+.. code-block::
+    
+    tox -e py38
+
+Where py38 matches your python version.
+
+Building the documentation
+--------------------------
+
+.. code-block::
+    
+    tox -e doc
+
+Building the package
+--------------------
+
+The package is built using `flit <https://flit.pypa.io/en/latest/#install>`_.
+
+You can build the PyPIM package with:
+
+.. code-block::
+    
+    flit build
+
+You can also directly install PyPIM in your current environment with:
+
+.. code-block::
+    
+    flit install
+
+Release Process
+---------------
+
+Releasing a new version is driven by git tags, created from the Github release
+page.
+
+1. Create the release branch, named ``release/v<version>``, where version does
+   not include the patch part. Eg. ``release/v0.5``, ``release/v1.2``
+2. In the ``release/v<version>`` branch, remove the ``.dev0`` suffix in
+   ``pyproject.toml`` and ``tests/test_metadata.py``
+3. Create a `new release <https://github.com/pyansys/pypim/releases/new>`_ with
+   a new tag named ``v<full_version>``, including the patch part, based on the latest
+   commit of the ``release/v<version>`` branch. Eg. ``v0.5.0``, ``v1.2.0``.
+4. In the ``main`` branch, increase the version, keeping the ``.dev0`` suffix.
+
+Patch versions are created from their release branch, by cherry-picking commits.
 
-PyPIM does not offer any functionality yet. Come back later!
+.. warning::
+    The git tag must match the committed package version.

doc/source/api/index.rst

@@ -4,6 +4,9 @@ API Reference
 
 This section gives an overview of the API of PyPIM.
 
+.. automodule:: ansys.platform.instancemanagement
+    :members:
+
 .. currentmodule:: ansys.platform.instancemanagement
 
 .. autosummary::

src/ansys/platform/instancemanagement/__init__.py

@@ -29,11 +29,42 @@ def is_configured() -> bool:
 def connect() -> Client:
     """Create a PyPIM client based on the environment configuration.
 
+    Before calling this method, ``is_configured()`` should be called to check if
+    the environment is configured to use PyPIM.
+
+    The environment configuration consists in setting the environment variable
+    ``ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG`` to the path of the PyPIM
+    configuration file. The configuration file is a simple json file containing
+    the URI of the Product Instance Management API and headers required to pass
+    information.
+
+    The configuration file format is:
+
+    .. code-block:: json
+
+        {
+            "version": 1,
+            "pim": {
+                "uri": "dns:pim.svc.com:80",
+                "headers": {
+                    "metadata-info": "value"
+                },
+                "tls": false
+            }
+        }
+
+
     Raises:
         RuntimeError: The environment is not configured to use PyPIM
 
     Returns:
         Client: A PyPIM client, the main entrypoint to use this library.
+
+
+    Examples:
+        >>> import ansys.platform.instancemanagement as pypim
+        >>> if pypim.is_configured():
+        >>>     client = pypim.connect()
     """
     if not is_configured():
         raise RuntimeError("The environment is not configured to use PyPIM.")

src/ansys/platform/instancemanagement/client.py

@@ -33,6 +33,13 @@ def __init__(self, channel: grpc.Channel) -> None:
 
         Args:
             channel: gRPC channel hosting the connection.
+
+        Examples:
+            >>> import ansys.platform.instancemanagement as pypim
+            >>> import grpc
+            >>> channel = grpc.insecure_channel("127.0.0.0:50001")
+            >>> client = pypim.Client(channel)
+
         """
         logger.info("Connecting")
         self._channel = channel
@@ -92,6 +99,14 @@ def definitions(
 
         Returns:
             Mapping[str, Definition]: The supported product definitions by name.
+
+        Examples:
+            >>> import ansys.platform.instancemanagement as pypim
+            >>> client = pypim.connect()
+            >>> for definition in client.definitions(product_name="mapdl"):
+            >>>     print(f"MAPDL version {definition.version} is available on the server.")
+                MAPDL version 221 is available on the server.
+
         """
         logger.debug(
             "Listing definitions for the product %s in version %s",
@@ -134,6 +149,8 @@ def create_instance(
     ) -> Instance:
         """Create a remote instance of a product based on its name and optionally its version.
 
+        This effectively starts the product in the backend, according to the backend configuration.
+
         The created instance will not yet be ready to use, you need to call `.wait_for_ready()`
         to wait for it to be ready.
 
@@ -147,6 +164,16 @@ def create_instance(
 
         Returns:
             Instance: An instance of the product.
+
+        Examples:
+            >>> import ansys.platform.instancemanagement as pypim
+            >>> client = pypim.connect()
+            >>> instance = client.create_instance(product_name="mapdl")
+            >>> instance.wait_for_ready()
+            >>> print(instance.services)
+            >>> instance.delete()
+                {'grpc': Service(uri='dns:10.240.4.231:50052', headers={})}
+
         """
         logger.debug(
             "Creating a product instance for %s in version %s", product_name, product_version

src/ansys/platform/instancemanagement/instance.py

@@ -146,6 +146,22 @@ def build_grpc_channel(self, service_name: str = "grpc", **kwargs):
 
         Returns:
             grpc.Channel: gRPC channel preconfigured to work with the instance.
+
+        Examples:
+            >>> import ansys.platform.instancemanagement as pypim
+            >>> from ansys.mapdl.core import Mapdl
+            >>> pim=pypim.connect()
+            >>> instance = pim.create_instance(product_name="mapdl", product_version="221")
+            >>> instance.wait_for_ready()
+            >>> channel = instance.build_grpc_channel(
+            >>>     options=[("grpc.max_receive_message_length", 8*1024**2)]
+            >>> )
+            >>> mapdl = Mapdl(channel=channel)
+            >>> print(mapdl)
+            >>> instance.delete()
+                Product:             Ansys Mechanical Enterprise
+                MAPDL Version:       22.1
+                ansys.mapdl Version: 0.61.2
         """
         if not self.ready:
             raise RuntimeError(f"The instance is not ready.")