Document how to disable caching rewritten .pyc files to disk

Also changed how the section is presented: instead of "Note" blocks, use proper
sections as those contain enough information to exist on their own.

Fix #1680

doc/en/assert.rst

@@ -252,8 +252,8 @@ the conftest file:
 .. _assert-details:
 .. _`assert introspection`:
 
-Advanced assertion introspection
-----------------------------------
+Assertion introspection details
+-------------------------------
 
 .. versionadded:: 2.1
 
@@ -266,9 +266,32 @@ supporting modules which are not themselves test modules will not be rewritten**
 
 You can manually enable assertion rewriting for an imported module by calling
 `register_assert_rewrite <https://docs.pytest.org/en/latest/writing_plugins.html#assertion-rewriting>`_
-before you import it (a good place to do that is in ``conftest.py``).
+before you import it (a good place to do that is in your root ``conftest.py``).
 
-.. note::
+For further information, Benjamin Peterson wrote up `Behind the scenes of pytest's new assertion rewriting <http://pybites.blogspot.com/2011/07/behind-scenes-of-pytests-new-assertion.html>`_.
+
+Assertion rewriting caches files on disk
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``pytest`` will write back the rewritten modules to disk for caching. You can disable
+this behavior (for example to avoid leaving stable ``.pyc`` files around in projects that
+move files around a lot) by adding this to the top of your ``conftest.py`` file:
+
+.. code-block:: python
+
+   import sys
+
+   sys.dont_write_bytecode = True
+
+Note that you still get the benefits of assertion introspection, only change is that
+the ``.pyc`` files won't be cached on disk.
+
+Additionally, rewriting will silently skip caching if it cannot write new ``.pyc`` files,
+i.e. in a read-only filesystem or a zipfile.
+
+
+Disabling assert rewriting
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``pytest`` rewrites test modules on import by using an import
 hook to write new ``pyc`` files. Most of the time this works transparently.
@@ -282,11 +305,6 @@ before you import it (a good place to do that is in ``conftest.py``).
 
 * Disable rewriting for all modules by using ``--assert=plain``.
 
-   Additionally, rewriting will fail silently if it cannot write new ``.pyc`` files,
-   i.e. in a read-only filesystem or a zipfile.
-
-
-For further information, Benjamin Peterson wrote up `Behind the scenes of pytest's new assertion rewriting <http://pybites.blogspot.com/2011/07/behind-scenes-of-pytests-new-assertion.html>`_.
 
 .. versionadded:: 2.1
    Add assert rewriting as an alternate introspection technique.