docs and rename

Author: tomvanmele

docs/userguide/cad.rhino8.rst

@@ -68,6 +68,52 @@ To create an editable install, you should update `pip` itself, first.
     $ ~/.rhinocode/py39-rh8/python3.9 -m pip install -e .
 
 
+Experimental Method
+===================
+
+COMPAS now makes the `install_in_rhino` command line utility available to simplify the installation of Python packages in Rhino 8 CPython.
+This utility is available after installing the main `compas` package:
+
+Install any Python package from PyPI
+
+.. code-block:: bash
+
+    install_in_rhino requests numpy
+
+Install from the current directory
+
+.. code-block:: bash
+
+    install_in_rhino .
+
+Install from a local path
+
+.. code-block:: bash
+
+    install_in_rhino path/to/package
+
+Install from a requirements file
+
+.. code-block:: bash
+
+    install_in_rhino -r requirements.txt
+
+Install in a specific site environment.
+
+.. code-block:: bash
+
+    install_in_rhino compas --env compas-dev
+
+Clear the site environment before installing
+
+.. code-block:: bash
+
+    install_in_rhino compas --env compas-dev --clear
+
+
+For more information, see :func:`compas_rhino.install_with_pip.install_in_rhino_with_pip`.
+
+
 Verification
 ============
 

src/compas_rhino/install_with_pip.py

@@ -33,15 +33,63 @@ def ensure_site_env(name: str) -> str:
     return fullname
 
 
-def install_package(
+def install_in_rhino_with_pip(
     packages: list[str],
     requirements: Optional[str] = None,
     env: str = "default",
     upgrade: bool = False,
     deps: bool = True,
     clear: bool = False,
 ):
-    """Install a package with Rhino's CPython pip."""
+    """Install a package with Rhino's CPython pip.
+
+    Parameters
+    ----------
+    packages : list of str
+        The package(s) to install (PyPI names or local package paths).
+    requirements : str, optional
+        Path to a requirements file.
+    env : str, optional
+        Name of the site env, without the random suffix.
+    upgrade : bool, optional
+        Attempt to upgrade packages already installed.
+    deps : bool, optional
+        If False, do not install dependencies.
+    clear : bool, optional
+        If True, clear the environment before installing.
+
+    Returns
+    -------
+    int
+        The return code from the pip install command.
+
+    Raises
+    ------
+    ValueError
+        If both packages and requirements are provided, or if neither are provided.
+
+    Examples
+    --------
+    >>> install_in_rhino_with_pip(packages=["requests"], env="myenv", upgrade=True)
+    >>> install_in_rhino_with_pip(requirements="requirements.txt", env="myenv")
+    >>> install_in_rhino_with_pip(packages=["."], env="myenv")
+    >>> install_in_rhino_with_pip(packages=[".."], env="myenv")
+
+    Notes
+    -----
+    This function is made available as a command line script under the name `install_in_rhino`.
+    On the command line you can use the following syntax
+
+    .. code-block:: bash
+
+        install_in_rhino requests numpy
+        install_in_rhino -r requirements.txt --env myenv --upgrade
+        install_in_rhino . --env myenv
+        install_in_rhino .. --env myenv
+        install_in_rhino -r requirements.txt --env myenv --no-deps
+        install_in_rhino requests --env myenv --clear
+
+    """
 
     if requirements and packages:
         raise ValueError("You must provide either packages or a requirements file, not both.")
@@ -103,7 +151,7 @@ def main():
     parser.set_defaults(deps=True)
     args = parser.parse_args()
 
-    install_package(
+    install_in_rhino_with_pip(
         packages=args.packages,
         requirements=args.requirements,
         env=args.env,
@@ -113,5 +161,9 @@ def main():
     )
 
 
+# =============================================================================
+# Main
+# =============================================================================
+
 if __name__ == "__main__":
     main()