Repository: mkdocs/mkdocs
Pull request #581 (2015-06-02 08:04:43)

If the site_dir is within the docs_dir, display a warning not an error


Patch:
diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md
index 4f1979f2..e0698123 100644
--- a/docs/about/release-notes.md
+++ b/docs/about/release-notes.md
@@ -13,6 +13,12 @@ You can determine your currently installed version using `mkdocs --version`:
     $ mkdocs --version
     mkdocs, version 0.13.0
 
+## Version 0.13.3 (2015-06-02)
+
+* Bugfix: Reduce validation error from to a warning if the site_dir is within
+  the docs_dir as this shouldn't cause any problems with building but will
+  inconvenience users building multiple times. (#580)
+
 ## Version 0.13.2 (2015-05-30)
 
 * Bugfix: Ensure all errors and warnings are logged before exiting. (#536)
@@ -21,7 +27,7 @@ You can determine your currently installed version using `mkdocs --version`:
 ## Version 0.13.1 (2015-05-27)
 
 * Bugfix: Fix a problem with minimal configurations which only contain a list
-  of paths in the pages config (#562)
+  of paths in the pages config. (#562)
 
 
 ## Version 0.13.0 (2015-05-26)
diff --git a/mkdocs/config/config_options.py b/mkdocs/config/config_options.py
index 7a01e16f..6b719b8c 100644
--- a/mkdocs/config/config_options.py
+++ b/mkdocs/config/config_options.py
@@ -231,10 +231,18 @@ class SiteDir(Dir):
         # and eventually make a deep nested mess.
         if config['docs_dir'].startswith(config['site_dir']):
             raise ValidationError(
-                "The 'docs_dir' can't be within the 'site_dir'.")
+                ("The 'docs_dir' should not be within the 'site_dir' as this "
+                 "can mean the source files are overwritten by the output or "
+                 "it will be deleted if --clean is passed to mkdocs build."
+                 "(site_dir: '{0}', docs_dir: '{1}')"
+                 ).format(config['site_dir'], config['docs_dir']))
         elif config['site_dir'].startswith(config['docs_dir']):
-            raise ValidationError(
-                "The 'site_dir' can't be within the 'docs_dir'.")
+            self.warnings.append(
+                ("The 'site_dir' should not be within the 'docs_dir' as this "
+                 "leads to the build directory being copied into itself and "
+                 "duplicate nested files in the 'site_dir'."
+                 "(site_dir: '{0}', docs_dir: '{1}')"
+                 ).format(config['site_dir'], config['docs_dir']))
 
 
 class ThemeDir(Dir):


Test patch:
diff --git a/mkdocs/tests/config/config_options_tests.py b/mkdocs/tests/config/config_options_tests.py
index 6a229558..1721bdd5 100644
--- a/mkdocs/tests/config/config_options_tests.py
+++ b/mkdocs/tests/config/config_options_tests.py
@@ -175,13 +175,10 @@ class SiteDirTest(unittest.TestCase):
         docs_dir = config_options.Dir()
 
         test_configs = (
-            {'docs_dir': 'docs', 'site_dir': j('docs', 'site')},
             {'docs_dir': j('site', 'docs'), 'site_dir': 'site'},
             {'docs_dir': 'docs', 'site_dir': '.'},
-            {'docs_dir': '.', 'site_dir': 'site'},
             {'docs_dir': '.', 'site_dir': '.'},
             {'docs_dir': 'docs', 'site_dir': ''},
-            {'docs_dir': '', 'site_dir': 'site'},
             {'docs_dir': '', 'site_dir': ''},
             {'docs_dir': j('..', 'mkdocs', 'docs'), 'site_dir': 'docs'},
         )
@@ -194,6 +191,30 @@ class SiteDirTest(unittest.TestCase):
             self.assertRaises(config_options.ValidationError,
                               option.post_validation, test_config, 'key')
 
+    def test_site_dir_in_docs_dir(self):
+
+        j = os.path.join
+
+        test_configs = (
+            {'docs_dir': 'docs', 'site_dir': j('docs', 'site')},
+            {'docs_dir': '.', 'site_dir': 'site'},
+            {'docs_dir': '', 'site_dir': 'site'},
+        )
+
+        for test_config in test_configs:
+
+            docs_dir = config_options.Dir()
+            option = config_options.SiteDir()
+
+            test_config['docs_dir'] = docs_dir.validate(test_config['docs_dir'])
+            test_config['site_dir'] = option.validate(test_config['site_dir'])
+
+            option.post_validation(test_config, 'key')
+            self.assertEqual(len(option.warnings), 1)
+            self.assertEqual(
+                option.warnings[0][:50],
+                "The 'site_dir' should not be within the 'docs_dir'")
+
 
 class ThemeTest(unittest.TestCase):
 
diff --git a/mkdocs/tests/config/config_tests.py b/mkdocs/tests/config/config_tests.py
index 36828403..afdc260a 100644
--- a/mkdocs/tests/config/config_tests.py
+++ b/mkdocs/tests/config/config_tests.py
@@ -175,13 +175,10 @@ class ConfigTests(unittest.TestCase):
         j = os.path.join
 
         test_configs = (
-            {'docs_dir': 'docs', 'site_dir': j('docs', 'site')},
             {'docs_dir': j('site', 'docs'), 'site_dir': 'site'},
             {'docs_dir': 'docs', 'site_dir': '.'},
-            {'docs_dir': '.', 'site_dir': 'site'},
             {'docs_dir': '.', 'site_dir': '.'},
             {'docs_dir': 'docs', 'site_dir': ''},
-            {'docs_dir': '', 'site_dir': 'site'},
             {'docs_dir': '', 'site_dir': ''},
             {'docs_dir': j('..', 'mkdocs', 'docs'), 'site_dir': 'docs'},
         )