expose and document programmatic API (#1592)

Signed-off-by: Bernat Gabor <bgabor8@bloomberg.net>

4 files changed, 28 insertions, 1 deletions

diff --git a/docs/changelog/1585.bugfix.rst b/docs/changelog/1585.bugfix.rst
new file mode 100644
index 0000000..91cb774
--- /dev/null
+++ b/docs/changelog/1585.bugfix.rst
@@ -0,0 +1 @@
+Expose a programmatic API as ``from virtualenv import cli_run`` - by :user:`gaborbernat`.
diff --git a/docs/changelog/1585.doc.rst b/docs/changelog/1585.doc.rst
new file mode 100644
index 0000000..47a865c
--- /dev/null
+++ b/docs/changelog/1585.doc.rst
@@ -0,0 +1,2 @@
+Document a programmatic API as ``from virtualenv import cli_run`` under :ref:`programmatic_api` -
+by :user:`gaborbernat`.
diff --git a/docs/render_cli.py b/docs/render_cli.py
index af350d1..4417c63 100644
--- a/docs/render_cli.py
+++ b/docs/render_cli.py
@@ -117,7 +117,7 @@ class CliTable(SphinxDirective):
             names = option["name"]
             default = option["default"]
             if default is not None:
-                if isinstance(default, str) and default[0] == default[-1] and default[0] == '"':
+                if isinstance(default, str) and default and default[0] == default[-1] and default[0] == '"':
                     default = default[1:-1]
                     if default == SUPPRESS:
                         default = None
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index 32b523a..fa178e7 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -180,3 +180,27 @@ also provisions a ``decativate`` command that will allow you to undo the operati
 A  longer explanation of this can be found within Allison Kaptur's 2013 blog post: `There's no magic: virtualenv
 edition <https://www.recurse.com/blog/14-there-is-no-magic-virtualenv-edition>`_ explains how virtualenv uses bash and
 Python and ``PATH`` and ``PYTHONHOME`` to isolate virtual environments' paths.
+
+.. _programmatic_api:
+
+Programmatic API
+----------------
+
+At the moment ``virtualenv`` offers only CLI level interface. If you want to trigger invocation of Python environments
+from within Python you should be using the ``virtualenv.cli_run`` method; this takes an ``args`` argument where you can
+pass the options the same way you would from the command line. The run will return a session object containing data
+about the created virtual environment.
+
+.. code-block:: python
+
+   from virtualenv import cli_run
+
+   cli_run(["venv"])
+
+.. automodule:: virtualenv
+   :members:
+
+.. currentmodule:: virtualenv.session
+
+.. autoclass:: Session
+    :members: