cli: add header or footer to nox -l

[henryiii]

How would this feature be useful?
nox -l is great; one of the best features is the fact that it shows the help text from the session's docstrings. It makes it a great entrypoint (and if there was a way to make the "default" be to show the sessions, such as nox.sessions = "-l", I'd probably tend to use that in most of my noxfiles). However, it would be very nice if there was a way to add general information at the top or bottom (don't care which) of that printout. For example, I often would like to add a little help snippet like this:

Run on all versions of Python with:
  docker run --rm -itv $PWD:/src -w /src quay.io/pypa/manylinux_2_24_x86_64:latest pipx run nox -s tests

since we've added support for running nox directly from pipx in the manylinux images, this is a handy note to add.

Describe the solution you'd like
This could either be something explicit like nox.header='...', or it could take the module docstring for the noxfile.

[cjolowicz]

I like this idea. The module docstring seems a good fit for this IMO, as we already use docstrings of session functions.

Would this be done unconditionally, or require some specific markup?

Looking at pip, pipx, urllib3, and Nox itself, only pip uses a module docstring, which is simply "Automation using nox". From this partial evidence, I'd say probably no need for specific markup.

[FollowTheProcess]

I use nox for all my python projects and I rate this idea!

Out of curiosity I forked and made a (very) naive implementation:

Which when you add the docstring at the top of noxfile.py:

Exhibits the desired behaviour:

I just took the functionality of load_nox_module and applied it here (hence naive). I'm assuming though that loading the module twice (even if just to get the __doc__) is not a good idea but I'm not really familiar enough with the rest of the nox machinery to know how best to handle this.

Do either of you have any pointers?

I'd be more than happy to implement this if so, I use nox a lot and would love the opportunity to contribute back (albeit a small amount).

Edit: We'd probably want to do a if __doc__ check too to ensure it doesn't print an unwanted empty string if __doc__ is not present

[cjolowicz]

Hi @FollowTheProcess

Thanks for your interest in implementing this!

The question is how to pass the user module, or just the docstring, from the load_nox_module task through to the honor_list_request task. You can see the machinery in workflow, which is passed the list of tasks by __main__.

My first thought would be to store the docstring in the session manifest (class Manifest) from within the discover_manifest task, which has access to both the user module (module) and the manifest. Then honor_list_request can access the docstring from there.

[FollowTheProcess]

@cjolowicz Thanks for the pointer! I'll play around a bit more and see what I can come up with!

[FollowTheProcess]

@cjolowicz I've had a first shot at this and have submitted a PR #459. Let me know what you think when you get a chance to look.

I also added some tests and fixed the ones I broke with this change. I was getting a failing test locally: tests/test_virtualenv.py::test__resolved_interpreter_nonstandard but I got that on initial clone too and I'm fairly certain it's not related.

[cjolowicz]

Fixed in #459