feat: add a nox --usage <session> command to print full docstrings for provided sessions (#1064)

* Add `--usage` command scaffold

Co-Authored-By: Thomas <5105354+thomaslapiana@users.noreply.github.com>

* Get docstring of a session function

* Add printing docstrings for usage CLI command

* Make help message clearer

* Fix bug with `default=False` sessions not working

* Add tests for `SessionRunner.full_description`

* Add some docs

* More tests

* Remove some lint

* Coverage

---------

Co-authored-by: Thomas <5105354+thomaslapiana@users.noreply.github.com>

Author: agriyakhetarpal

README.md

@@ -67,6 +67,12 @@ python3 -m pip install --user nox
 nox -l/--list
 ```
 
+### Get help on a particular session (if it has a docstring)
+
+```shell
+nox --usage test
+```
+
 ### Run all sessions
 
 ```shell

docs/config.rst

@@ -54,6 +54,17 @@ The ``nox --list`` command will show:
     Available sessions:
     * tests -> Run the test suite.
 
+The ``--list`` command shows the first line of the docstring as the session's description. You can also
+show the full docstring of a session using the ``--usage`` option, especially if it has multiple lines.
+For example:
+
+.. code-block:: console
+
+    $ nox --usage tests
+    Run the test suite.
+
+    The test suite consists of all tests in tests/.
+
 
 Session name
 ------------

docs/usage.rst

@@ -35,6 +35,11 @@ get json output for the selected session. Fields include ``session`` (pretty
 name), ``name``, ``description``, ``python`` (null if not specified), ``tags``,
 and ``call_spec`` (for parametrized sessions).
 
+To get more information about one particular session at a time, you can use ``--usage``:
+
+.. code-block:: console
+
+    nox --usage tests
 
 .. _session_execution_order:
 

nox/_cli.py

@@ -61,6 +61,7 @@ def execute_workflow(args: Namespace) -> int:
             tasks.discover_manifest,
             tasks.filter_manifest,
             tasks.honor_list_request,
+            tasks.honor_usage_request,
             tasks.run_manifest,
             tasks.print_summary,
             tasks.create_report,

nox/_options.py

@@ -364,6 +364,13 @@ def _tag_completer(
         action="store_true",
         help="List all available sessions and exit.",
     ),
+    _option_set.Option(
+        "usage",
+        "--usage",
+        group=options.groups["sessions"],
+        nargs=1,
+        help="Print the full docstring of a given session and exit. Raises if there is no docstring.",
+    ),
     _option_set.Option(
         "json",
         "--json",

nox/sessions.py

@@ -18,6 +18,7 @@
 import datetime
 import enum
 import hashlib
+import inspect
 import os
 import pathlib
 import re
@@ -1011,6 +1012,13 @@ def description(self) -> str | None:
             return doc.strip().split("\n")[0]
         return None
 
+    @property
+    def full_description(self) -> str | None:
+        doc = self.func.__doc__
+        if doc:
+            return inspect.cleandoc(doc)
+        return None
+
     def __str__(self) -> str:
         sigs = ", ".join(self.signatures)
         return f"Session(name={self.name}, signatures={sigs})"

nox/tasks.py

@@ -336,6 +336,44 @@ def honor_list_request(manifest: Manifest, global_config: Namespace) -> Manifest
     return 0
 
 
+def honor_usage_request(manifest: Manifest, global_config: Namespace) -> Manifest | int:
+    """If --usage was passed, print the full docstring of the session and exit.
+    Raise an error if the session does not exist or has no docstring to print.
+
+    Args:
+        manifest (~.Manifest): The manifest of sessions to be run.
+        global_config (~nox.main.GlobalConfig): The global configuration.
+
+    Returns:
+        Union[~.Manifest,int]: ``0`` if usage is printed,
+            the manifest otherwise (to be sent to the next task).
+    """
+    if not global_config.usage:
+        return manifest
+
+    name = global_config.usage[0]
+
+    # Search all sessions, not just the filtered queue, so that
+    # non-default sessions can also be looked up.
+    session = None
+    for _ in manifest._all_sessions:
+        if _.name == name or name in _.signatures:
+            session = _
+            break
+
+    if session is None:
+        logger.error("Session %s not found.", name)
+        return 1
+
+    full_description = session.full_description
+    if full_description is None:
+        logger.error("Session %s has no docstring.", name)
+        return 1
+
+    print(full_description)
+    return 0
+
+
 def run_manifest(manifest: Manifest, global_config: Namespace) -> list[Result]:
     """Run the full manifest of sessions.
 

tests/test_sessions.py

@@ -1196,6 +1196,37 @@ def foo() -> None:
         runner.func = foo  # type: ignore[assignment]
         assert runner.description is None
 
+    def test_full_description_property_one_line(self) -> None:
+        def foo() -> None:
+            """Just one line"""
+
+        runner = self.make_runner()
+        runner.func = foo  # type: ignore[assignment]
+        assert runner.full_description == "Just one line"
+
+    def test_full_description_property_multi_line(self) -> None:
+        def foo() -> None:
+            """Multiline
+
+            Extra description
+            with more details
+            """
+
+        runner = self.make_runner()
+        runner.func = foo  # type: ignore[assignment]
+        assert (
+            runner.full_description
+            == "Multiline\n\nExtra description\nwith more details"
+        )
+
+    def test_full_description_property_no_doc(self) -> None:
+        def foo() -> None:
+            pass
+
+        runner = self.make_runner()
+        runner.func = foo  # type: ignore[assignment]
+        assert runner.full_description is None
+
     def test__create_venv_process_env(self) -> None:
         runner = self.make_runner()
         runner.func.python = False

tests/test_tasks.py

@@ -786,6 +786,73 @@ def test_create_report() -> None:
         open_.assert_called_once_with("/path/to/report", "w", encoding="utf-8")
 
 
+def test_honor_usage_request_noop() -> None:
+    config = _options.options.namespace(usage=None)
+    manifest = typing.cast("Manifest", {"thing": mock.sentinel.THING})
+    return_value = tasks.honor_usage_request(manifest, global_config=config)
+    assert return_value is manifest
+
+
+def test_honor_usage_request_with_docstring(
+    capsys: pytest.CaptureFixture[builtins.str],
+) -> None:
+    config = _options.options.namespace(usage=["my_session"])
+    manifest = mock.create_autospec(Manifest)
+    session = argparse.Namespace(
+        name="my_session",
+        signatures=["my_session"],
+        full_description="Full docstring\n\nWith details",
+    )
+    manifest._all_sessions = [session]
+    return_value = tasks.honor_usage_request(manifest, global_config=config)
+    assert return_value == 0
+    out = capsys.readouterr().out
+    assert "Full docstring\n\nWith details" in out
+
+
+def test_honor_usage_request_no_docstring() -> None:
+    config = _options.options.namespace(usage=["my_session"])
+    manifest = mock.create_autospec(Manifest)
+    session = argparse.Namespace(
+        name="my_session",
+        signatures=["my_session"],
+        full_description=None,
+    )
+    manifest._all_sessions = [session]
+    return_value = tasks.honor_usage_request(manifest, global_config=config)
+    assert return_value == 1
+
+
+def test_honor_usage_request_skips_non_matching_sessions(
+    capsys: pytest.CaptureFixture[builtins.str],
+) -> None:
+    config = _options.options.namespace(usage=["second"])
+    manifest = mock.create_autospec(Manifest)
+    first = argparse.Namespace(
+        name="first",
+        signatures=["first"],
+        full_description="First docstring",
+    )
+    second = argparse.Namespace(
+        name="second",
+        signatures=["second"],
+        full_description="Second docstring",
+    )
+    manifest._all_sessions = [first, second]
+    return_value = tasks.honor_usage_request(manifest, global_config=config)
+    assert return_value == 0
+    out = capsys.readouterr().out
+    assert "Second docstring" in out
+
+
+def test_honor_usage_request_session_not_found() -> None:
+    config = _options.options.namespace(usage=["nonexistent"])
+    manifest = mock.create_autospec(Manifest)
+    manifest._all_sessions = []
+    return_value = tasks.honor_usage_request(manifest, global_config=config)
+    assert return_value == 1
+
+
 def test_final_reduce() -> None:
     config = argparse.Namespace()
     true = typing.cast("sessions.Result", True)  # noqa: FBT003