Add code commentary to poetry venv creation.

Issue #6 raised the question why running `poetry env info --path` was
needed. Since this wasn't documented before, I added a few code comments
to explain.

* sphinx_polyversion/pyvenv.py (Poetry) : commentary

Author: real-yfprojects

sphinx_polyversion/pyvenv.py

@@ -230,7 +230,11 @@ def __init__(self, path: Path, name: str, *, args: Iterable[str]):
         args : Iterable[str]
             The cmd arguments to pass to `poetry install`.
         """
-        super().__init__(path, name, path / ".venv")
+        super().__init__(
+            path,
+            name,
+            path / ".venv",  # placeholder, determined later
+        )
         self.args = args
 
     async def __aenter__(self) -> Self:
@@ -276,7 +280,12 @@ async def __aenter__(self) -> Self:
                 cast(int, process.returncode), " ".join(cmd), out, err
             )
 
-        # locate venv
+        # ---- locate venv
+        # In the previous process poetry will have created or
+        # ensured the existence of a venv in `venv_path` path folder.
+        # However the venv itself constitutes a subdirectory with
+        # an arbitrary name generated by poetry.
+        # Thus we ask poetry to give as the name of the venv folder.
         cmd: list[str] = ["poetry", "env", "info", "--path"]
         process = await asyncio.create_subprocess_exec(
             *cmd, cwd=self.path, env=env, stdout=PIPE, stderr=PIPE
@@ -291,7 +300,8 @@ async def __aenter__(self) -> Self:
             raise BuildError from CalledProcessError(
                 cast(int, process.returncode), " ".join(cmd), out, err
             )
-        self.venv = Path(out)
+        self.venv = Path(out)  # actual venv location
+
         return self