fix: improve messaging on QPU and compiler timeout

docs/source/troubleshooting.rst

@@ -7,6 +7,35 @@ If you're having any trouble running your pyQuil programs locally or on the QPU,
 following things before sending a support request. It will save you time and make it easier for us
 to help!
 
+Timeout in Compilation
+----------------------
+
+This may occur due to the size of your program, problems with your local ``quilc`` service, or problems
+with the remote QCS API.
+
+1. Ensure that ``quilc`` is running, per the compiler documentation: :ref:`compiler`.
+2. Try compiling and running a smaller program, or one that previously worked.
+3. If you have a larger program and expect it to take a long time to compile, set a higher ``compiler_timeout``
+   value per the instructions here: :ref:`compiler`.
+
+Timeout in Execution
+--------------------
+
+This may occur due to one of several different problems. Often, it's because you don't have network access
+to the execution endpoint.
+
+If you're running against the QVM, ensure that it is properly running: :ref:`server`. If you're using docker,
+you can check this using ``docker ps``.
+
+If you're running against the QPU, ensure that you are running your program from a supported environment.
+Live Rigetti QPUs are **only accessible from Rigetti-provided environments**, such as
+`JupyterHub <https://jupyterhub.qcs.rigetti.com>`_. If you are running from anywhere else, such as a
+script on your local computer or a public cloud virtual machine,
+**your program will not be able to reach a QPU and will time out**.
+
+Collect Debug Information
+----------------------------
+
 1. Ensure that your pyQuil version is up to date. If you're using ``pip``, you can do this with
    ``pip freeze``. Within your script, you can use ``__version__``:
 
@@ -30,12 +59,17 @@ to help!
 
     LOG_LEVEL=DEBUG pyquil my_script.py
 
+   or
+
    .. code:: python
 
     import logging
     from pyquil.api._logger import logger
 
     logger.setLevel(logging.DEBUG)
 
-If the problem still isn't clear, then we can help! Please contact us at our
-`support page <https://rigetti.zendesk.com>`_. Thanks for using pyQuil!
+If the problem still isn't clear, then we can help! Please file an issue
+on the `GitHub repo <https://github.com/rigetti/pyquil>`_ if it's an issue with pyQuil itself,
+or contact us at our `support page <https://rigetti.zendesk.com>`_ for problems with QCS.
+
+Thanks for using pyQuil!

pyquil/_version.py

@@ -14,10 +14,18 @@
 #    limitations under the License.
 ##############################################################################
 import sys
+from packaging.version import parse
+
 
 if sys.version_info < (3, 8):
     from importlib_metadata import version
 else:
     from importlib.metadata import version
 
 pyquil_version = version(__package__)  # type: ignore
+pyquil_docs_version = parse(pyquil_version).base_version or "stable"
+
+DOCS_URL = f"https://pyquil-docs.rigetti.com/en/{pyquil_docs_version}"
+"""
+The URL of the hosted docs for this package version.
+"""

pyquil/api/_abstract_compiler.py

@@ -149,7 +149,8 @@ def _connect(self) -> None:
             raise QuilcNotRunning(
                 f"Request to quilc at {self._compiler_client.base_url} timed out. "
                 "This could mean that quilc is not running, is not reachable, or is "
-                "responding slowly."
+                "responding slowly. See the Troubleshooting Guide: "
+                "{DOCS_URL}/troubleshooting.html"
             )
 
     @abstractmethod

pyquil/api/_qpu_client.py

@@ -25,6 +25,7 @@
 from retry import retry
 
 from pyquil.api import EngagementManager
+from pyquil._version import DOCS_URL
 
 
 @dataclass
@@ -195,6 +196,11 @@ def _rpcq_request(self, method_name: str, *args: Any, **kwargs: Any) -> Any:
         )
         try:
             return client.call(method_name, *args, **kwargs)
+        except TimeoutError as e:
+            raise TimeoutError(
+                f"Request to QPU at {engagement.address} timed out. "
+                f"See the Troubleshooting Guide: {DOCS_URL}/troubleshooting.html"
+            ) from e
         finally:
             client.close()  # type: ignore