Refresh tutorial and fixup small docs things (#190)

docs/config.rst

@@ -7,13 +7,16 @@ Noxfile
 Nox looks for configuration in a file named `noxfile.py` by default. You can specify
 a different file using the ``--noxfile`` argument when running ``nox``.
 
+
 Defining sessions
 -----------------
 
 .. autofunction:: nox.session
 
 Nox sessions are configured via standard Python functions that are decorated
-with ``@nox.session``. For example::
+with ``@nox.session``. For example:
+
+.. code-block:: python
 
     import nox
 
@@ -28,7 +31,9 @@ Session description
 -------------------
 
 You can add a description to your session using a `docstring <https://www.python.org/dev/peps/pep-0257>`__.
-The first line will be shown when listing the sessions. For example::
+The first line will be shown when listing the sessions. For example:
+
+.. code-block:: python
 
     import nox
 
@@ -49,8 +54,9 @@ The ``nox --list`` command will show:
 Session name
 ------------
 
-By default Nox uses the decorated function's name as the session name. This works wonderfully for the vast majority of projects, however, if you need to you can customize the session's name by using the ``name`` argument to ``@nox.session``. For example::
+By default Nox uses the decorated function's name as the session name. This works wonderfully for the vast majority of projects, however, if you need to you can customize the session's name by using the ``name`` argument to ``@nox.session``. For example:
 
+.. code-block:: python
 
     import nox
 
@@ -74,32 +80,41 @@ And you can tell ``nox`` to run the session using the custom name:
     $ nox --session "custom-name"
     Hello!
 
+
 .. _virtualenv config:
 
 Configuring a session's virtualenv
 ----------------------------------
 
 By default, Nox will create a new virtualenv for each session using the same interpreter that Nox uses. If you installed Nox using Python 3.6, Nox will use Python 3.6 by default for all of your sessions.
 
-You can tell Nox to use a different Python interpreter/version by specifying the ``python``  argument (or its alias ``py``) to ``@nox.session``::
+You can tell Nox to use a different Python interpreter/version by specifying the ``python``  argument (or its alias ``py``) to ``@nox.session``:
+
+.. code-block:: python
 
     @nox.session(python='2.7')
     def tests(session):
         pass
 
-You can also tell Nox to run your session against multiple Python interpreters. Nox will create a separate virtualenv and run the session for each interpreter you specify. For example, this session will run twice - once for Python 2.7 and once for Python 3.6::
+You can also tell Nox to run your session against multiple Python interpreters. Nox will create a separate virtualenv and run the session for each interpreter you specify. For example, this session will run twice - once for Python 2.7 and once for Python 3.6:
+
+.. code-block:: python
 
     @nox.session(python=['2.7', '3.6'])
     def tests(session):
         pass
 
-When you provide a version number, Nox automatically prepends python to determine the name of the executable. However, Nox also accepts the full executable name. If you want to test using pypy, for example::
+When you provide a version number, Nox automatically prepends python to determine the name of the executable. However, Nox also accepts the full executable name. If you want to test using pypy, for example:
+
+.. code-block:: console
 
     @nox.session(python=['2.7', '3.6', 'pypy-6.0'])
     def tests(session):
         pass
 
-When collecting your sessions, Nox will create a separate session for each interpreter. You can see these sesions when running ``nox --list``. For example this Noxfile::
+When collecting your sessions, Nox will create a separate session for each interpreter. You can see these sesions when running ``nox --list``. For example this Noxfile:
+
+.. code-block:: python
 
     @nox.session(python=['2.7', '3.5', '3.6', '3.7'])
     def tests(session):
@@ -116,13 +131,17 @@ Will produce these sessions:
 
 Note that this expansion happens *before* parameterization occurs, so you can still parametrize sessions with multiple interpreters.
 
-If you want to disable virtualenv creation altogether, you can set ``python`` to ``False``::
+If you want to disable virtualenv creation altogether, you can set ``python`` to ``False``:
+
+.. code-block:: python
 
     @nox.session(python=False)
     def tests(session):
         pass
 
-Finally you can also specify that the virtualenv should *always* be reused instead of recreated every time::
+Finally you can also specify that the virtualenv should *always* be reused instead of recreated every time:
+
+.. code-block:: python
 
     @nox.session(
         python=['2.7', '3.6'],
@@ -131,13 +150,177 @@ Finally you can also specify that the virtualenv should *always* be reused inste
         pass
 
 
-Using the session object
-------------------------
+Passing arguments into sessions
+-------------------------------
+
+Often it's useful to pass arguments into your test session. Here's a quick
+example that demonstrates how to use arguments to run tests against a
+particular file:
+
+.. code-block:: python
+
+    @nox.session
+    def test(session):
+        session.install('pytest')
+
+        if session.posargs:
+            test_files = session.posargs
+        else:
+            test_files = ['test_a.py', 'test_b.py']
+
+        session.run('pytest', *test_files)
+
+Now you if you run:
+
+
+.. code-block:: console
+
+    nox
+
+
+Then nox will run:
+
+.. code-block:: console
+
+    pytest test_a.py test_b.py
+
+
+But if you run:
+
+.. code-block:: console
+
+    nox -- test_c.py
+
+
+Then nox will run:
+
+.. code-block:: console
+
+    pytest test_c.py
+
+
+.. _parametrized:
+
+Parametrizing sessions
+----------------------
+
+Session arguments can be parametrized with the :func:`nox.parametrize` decorator. Here's a typical example of parametrizing the Django version to install:
+
+.. code-block:: python
+
+    @nox.session
+    @nox.parametrize('django', ['1.9', '2.0'])
+    def tests(session, django):
+        session.install(f'django=={django}')
+        session.run('pytest')
+
+When you run ``nox``, it will create a two distinct sessions:
+
+.. code-block:: console
+
+    $ nox
+    nox > Running session tests(django='1.9')
+    nox > pip install django==1.9
+    ...
+    nox > Running session tests(djano='2.0')
+    nox > pip install django==2.0
+
+
+:func:`nox.parametrize` has an interface and usage intentionally similar to `pytest's parametrize <https://pytest.org/latest/parametrize.html#_pytest.python.Metafunc.parametrize>`_.
+
+.. autofunction:: nox.parametrize
+
+You can also stack the decorator to produce sessions that are a combination of the arguments, for example:
+
+.. code-block:: python
+
+    @nox.session
+    @nox.parametrize('django', ['1.9', '2.0'])
+    @nox.parametrize('database', ['postgres', 'mysql'])
+    def tests(session, django, database):
+        ...
+
+
+If you run ``nox --list``, you'll see that this generates the following set of sessions:
+
+.. code-block:: console
+
+    * tests(django='1.9', database='postgres')
+    * tests(django='2.0', database='mysql')
+    * tests(django='1.9', database='postgres')
+    * tests(django='2.0', database='mysql')
+
+
+If you only want to run one of the parametrized sessions, see :ref:`running_paramed_sessions`.
+
+
+Giving friendly names to parametrized sessions
+----------------------------------------------
+
+The automatically generated names for parametrized sessions, such as ``tests(django='1.9', database='postgres')``, can be long and unwieldy to work with even with using :ref:`keyword filtering <opt-sessions-and-keywords>`. You can give parametrized sessions custom IDs to help in this scenario. These two examples are equivalent:
+
+.. code-block:: python
+
+    @nox.session
+    @nox.parametrize('django',
+        ['1.9', '2.0'],
+        ids=['old', 'new'])
+    def tests(session, django):
+        ...
+
+.. code-block:: python
+
+    @nox.session
+    @nox.parametrize('django', [
+        nox.param('1.9', id='old'),
+        nox.param('2.0', id='new'),
+    ])
+    def tests(session, django):
+        ...
+
+When running ``nox --list`` you'll see their new IDs:
+
+.. code-block:: console
+
+    * tests(old)
+    * tests(new)
+
+And you can run them with ``nox --sessions "tests(old)"`` and so on.
+
+This works with stacked parameterizations as well. The IDs are combined during the combination. For example:
+
+.. code-block:: python
+
+    @nox.session
+    @nox.parametrize(
+        'django',
+        ['1.9', '2.0'],
+        ids=["old", "new"])
+    @nox.parametrize(
+        'database',
+        ['postgres', 'mysql'],
+        ids=["psql", "mysql"])
+    def tests(session, django, database):
+        ...
+
+Produces these sessions when running ``nox --list``:
+
+.. code-block:: console
+
+    * tests(psql, old)
+    * tests(mysql, old)
+    * tests(psql, new)
+    * tests(mysql, new)
+
+
+
+The session object
+------------------
 
 .. module:: nox.sessions
 
-Nox will call your session functions with a :class:`Session` object.
-You can use this object to run various commands in your session.
+Nox will call your session functions with a an instance of the :class:`Session`
+class.
 
 .. autoclass:: Session
     :members: