Add chapter about nested fake filesystems to troubleshouting guide

3 files changed, 67 insertions, 21 deletions

diff --git a/CHANGES.md b/CHANGES.md
index bfbad4a..640a73a 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -4,38 +4,38 @@ The released versions correspond to PyPI releases.
 ## Unreleased
 
 ### Changes
-* The handling of file permissions under Posix is should now mostly match the behavior
+* the handling of file permissions under Posix is should now mostly match the behavior
   of the real filesystem, which may change the behavior of some tests
 
 ### Fixes
-* Fixed a specific problem on reloading a pandas-related module (see [#947](../../issues/947)),
+* fixed a specific problem on reloading a pandas-related module (see [#947](../../issues/947)),
   added possibility for unload hooks for specific modules
-* Use this also to reload django views (see [#932](../../issues/932))
-* Fixed `EncodingWarning` for Python >= 3.11 (see [#957](../../issues/957))
-* Consider directory ownership while adding or removing directory entries
+* use this also to reload django views (see [#932](../../issues/932))
+* fixed `EncodingWarning` for Python >= 3.11 (see [#957](../../issues/957))
+* consider directory ownership while adding or removing directory entries
   (see [#959](../../issues/959))
-* Fixed handling of directory enumeration and search permissions under Posix systems
+* fixed handling of directory enumeration and search permissions under Posix systems
   (see [#960](../../issues/960))
 
 ## [Version 5.3.5](https://pypi.python.org/pypi/pyfakefs/5.3.5) (2024-01-30)
 Fixes a regression.
 
 ### Fixes
-* Fixes a regression due to the changed behavior of the dynamic patcher cleanup (see [#939](../../issues/939)).
+* Fixed a regression due to the changed behavior of the dynamic patcher cleanup (see [#939](../../issues/939)).
   The change is now by default only made if the `django` module is loaded, and the behavior can
   be changed using the new argument `module_cleanup_mode`.
 
 ### Packaging
-* include `tox.ini` and a few more files into the source distribution (see [#937](../../issues/937))
+* included `tox.ini` and a few more files into the source distribution (see [#937](../../issues/937))
 
 ## [Version 5.3.4](https://pypi.python.org/pypi/pyfakefs/5.3.4) (2024-01-19)
 Bugfix release.
 
 ### Fixes
-* fixes handling of unhashable modules which cannot be cached (see [#923](../../issues/923))
+* fixed handling of unhashable modules which cannot be cached (see [#923](../../issues/923))
 * reload modules loaded by the dynamic patcher instead of removing them - sometimes they may
   not be reloaded automatically (see [#932](../../issues/932))
-* add back argument `use_dynamic_patch` as a fallback for similar problems
+* added back argument `use_dynamic_patch` as a fallback for similar problems
 
 
 ## [Version 5.3.2](https://pypi.python.org/pypi/pyfakefs/5.3.2) (2023-11-30)
@@ -58,23 +58,23 @@ Mostly a bugfix release.
   to an existing directory in the fake filesystem (see [#901](../../issues/901))
 
 ### Fixes
-* fixes the problem that filesystem patching was still active in the pytest
+* fixed the problem that filesystem patching was still active in the pytest
   logreport phase (see [#904](../../issues/904))
-* Restores compatibility with PyTorch 2.0 and above, as well as with other
-  classes that have custom __setattr__ methods (see [#905](../../pull/905)).
+* restored compatibility with PyTorch 2.0 and above, as well as with other
+  classes that have custom __setattr__ methods (see [#905](../../pull/905))
 
 ## [Version 5.3.0](https://pypi.python.org/pypi/pyfakefs/5.3.0) (2023-10-11)
 Adds official support for Python 3.12.
 
 ### Changes
-* add official support for Python 3.12
+* added official support for Python 3.12
 
 ### Fixes
 * removed a leftover debug print statement (see [#869](../../issues/869))
 * make sure tests work without HOME environment set (see [#870](../../issues/870))
 * automount drive or UNC path under Windows if needed for `pathlib.Path.mkdir()`
   (see [#890](../../issues/890))
-* adapt patching `io.open` and `io.open_code` to work with Python 3.12
+* adapted patching `io.open` and `io.open_code` to work with Python 3.12
   (see [#836](../../issues/836) and [#892](../../issues/892))
 
 ## [Version 5.2.4](https://pypi.python.org/pypi/pyfakefs/5.2.4) (2023-08-18)
@@ -91,12 +91,12 @@ Adds compatibility with PyPy 3.10 and Python 3.12.
 ### Fixes
 * Re-create temp directory if it had been created before on resetting file system
   (see [#814](../../issues/814)).
-* Exclude pytest `pathlib` modules from patching to avoid mixup of patched/unpatched
+* Excluded pytest `pathlib` modules from patching to avoid mixup of patched/unpatched
   code (see [#814](../../issues/814)).
-* Adapt to changes in Python 3.12 beta1 (only working partially,
+* Adapted to changes in Python 3.12 beta1 (only working partially,
   see [#830](../../issues/830) and [#831](../../issues/831)).
-* Adapt to changes in `shutil` in Python 3.12 beta2 (see [#814](../../issues/814)).
-* Fix support for newer PyPi versions (see [#859](../../issues/859)).
+* Adapted to changes in `shutil` in Python 3.12 beta2 (see [#814](../../issues/814)).
+* Fixed support for newer PyPi versions (see [#859](../../issues/859)).
 
 ### Documentation
 * Added a note regarding the incompatibility of the built-in `sqlite3` module with
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index d02551b..56572aa 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -134,6 +134,8 @@ from configuration files. In these cases, you have to map the respective files
 or directories from the real into the fake filesystem as described in
 :ref:`real_fs_access`. For the timezone example, this could look like the following::
 
+.. code:: python
+
     from pathlib import Path
     import pytz
     from pyfakefs.fake_filesystem_unittest import TestCase
@@ -150,13 +152,15 @@ or directories from the real into the fake filesystem as described in
 If you are using Django, various dependencies may expect both the project
 directory and the ``site-packages`` installation to exist in the fake filesystem.
 
-Here's an example of how to add these using pytest::
+Here's an example of how to add these using pytest:
 
+.. code:: python
 
     import os
     import django
     import pytest
 
+
     @pytest.fixture
     def fake_fs(fs):
         PROJECT_BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -279,6 +283,48 @@ is problematic and better avoided.
   `pathlib` has been restructured so that a pathlib path no longer contains a reference
   to the original filesystem accessor, and it can safely be used in the fake filesystem.
 
+.. _nested_patcher_invocation:
+
+Nested file system fixtures and Patcher invocations
+---------------------------------------------------
+``pyfakefs`` does not support nested faked file systems. Instead, it uses reference counting
+on the single fake filesystem instance. That means, if you are trying to create a fake filesystem
+inside a fake filesystem, only the reference count will increase, and any arguments you may pass
+to the patcher or fixture are ignored. Likewise, if you leave a nested fake filesystem,
+only the reference count is decreased and nothing is reverted.
+
+There are some situations where that may happen, probably without you noticing:
+
+* If you use the module- or session based variants of the ``fs`` fixture (e.g. ``fs_module`` or
+  ``fs_session``), you may still use the ``fs`` fixture in single tests. This will practically
+  reference the module- or session based fake filesystem, instead of creating a new one.
+
+.. code:: python
+
+  @pytest.fixture(scope="module", autouse=True)
+  def use_fs(fs_module):
+      # do some setup...
+      yield fs_module
+
+
+  def test_something(fs):
+      do_more_fs_setup()
+      test_something()
+      # the fs setup done in this test is not reverted!
+
+* If you invoke a ``Patcher`` instance inside a test with the ``fs`` fixture (or with an active
+  ``fs_module`` or ``fs_session`` fixture), this will be ignored. For example:
+
+.. code:: python
+
+  def test_something(fs):
+      with Patcher(allow_root_user=False):
+          # root user is still allowed
+          do_stuff()
+
+* The same is true, if you use ``setUpPyfakefs`` or ``setUpClassPyfakefs`` in a unittest context, or if you use
+  the ``patchfs`` decorator. ``Patcher`` instances created in the tests will be ignored likewise.
+
 
 .. _`multiprocessing`: https://docs.python.org/3/library/multiprocessing.html
 .. _`subprocess`: https://docs.python.org/3/library/subprocess.html
diff --git a/docs/usage.rst b/docs/usage.rst
index 5332541..9cfe0ed 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -51,7 +51,7 @@ respectively.
   not setup / tear down the fake filesystem in the current scope; instead, it
   will just serve as a reference to the active fake filesystem. That means that changes
   done in the fake filesystem inside a test will remain there until the respective scope
-  ends.
+  ends (see also :ref:`nested_patcher_invocation`).
 
 Patch using fake_filesystem_unittest
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~