Exclude theme from watched files by default.

Add a --watch-theme option which theme devs can enable if needed.
Most users never modify the theme files and watchers are resource hogs.
Fixes #2092.

docs/about/release-notes.md

@@ -21,7 +21,19 @@ The current and past members of the MkDocs team.
 * [@d0ugal](https://github.com/d0ugal/)
 * [@waylan](https://github.com/waylan/)
 
-## Version 1.1.3 (Under development)
+## Version 1.2 (Under development)
+
+### Major Additions to Version 1.2
+
+##### Backward Incompatible Changes
+
+A theme's files are now excluded from the list of watched files by default
+when using the `--livereload` server. This new default behavior is what most
+users need and provides better performance when editing site content.
+Theme developers can enable the old behavior with the `--watch-theme`
+option. (#2092).
+
+### Other Changes and Additions to Version 1.2
 
 * Bugfix: Properly process navigation child items in `_get_by_type` when
   filtering for sections (#2203).

mkdocs/__main__.py

@@ -56,6 +56,8 @@ remote_name_help = ("The remote name to commit to for Github Pages. This "
                     "overrides the value specified in config")
 force_help = "Force the push to the repository."
 ignore_version_help = "Ignore check that build is not being deployed with an older version of MkDocs."
+watch_theme_help = ("Include the theme in list of files to watch for live reloading. "
+                    "Ignored when live reload is not used.")
 
 
 def add_options(opts):
@@ -122,6 +124,7 @@ def cli():
 @click.option('--livereload', 'livereload', flag_value='livereload', help=reload_help, default=True)
 @click.option('--no-livereload', 'livereload', flag_value='no-livereload', help=no_reload_help)
 @click.option('--dirtyreload', 'livereload', flag_value='dirty', help=dirty_reload_help)
+@click.option('--watch-theme', help=watch_theme_help, is_flag=True)
 @common_config_options
 @common_options
 def serve_command(dev_addr, livereload, **kwargs):

mkdocs/commands/serve.py

@@ -48,7 +48,7 @@ def _get_handler(site_dir, StaticFileHandler):
     return WebHandler
 
 
-def _livereload(host, port, config, builder, site_dir):
+def _livereload(host, port, config, builder, site_dir, watch_theme):
 
     # We are importing here for anyone that has issues with livereload. Even if
     # this fails, the --no-livereload alternative should still work.
@@ -69,8 +69,9 @@ def _livereload(host, port, config, builder, site_dir):
     server.watch(config['docs_dir'], builder)
     server.watch(config['config_file_path'], builder)
 
-    for d in config['theme'].dirs:
-        server.watch(d, builder)
+    if watch_theme:
+        for d in config['theme'].dirs:
+            server.watch(d, builder)
 
     # Run `serve` plugin events.
     server = config['plugins'].run_event('serve', server, config=config, builder=builder)
@@ -103,7 +104,7 @@ def _static_server(host, port, site_dir):
 
 
 def serve(config_file=None, dev_addr=None, strict=None, theme=None,
-          theme_dir=None, livereload='livereload', **kwargs):
+          theme_dir=None, livereload='livereload', watch_theme=False, **kwargs):
     """
     Start the MkDocs development server
 
@@ -143,7 +144,7 @@ def serve(config_file=None, dev_addr=None, strict=None, theme=None,
         host, port = config['dev_addr']
 
         if livereload in ['livereload', 'dirty']:
-            _livereload(host, port, config, builder, site_dir)
+            _livereload(host, port, config, builder, site_dir, watch_theme)
         else:
             _static_server(host, port, site_dir)
     finally:

mkdocs/tests/cli_tests.py

@@ -28,7 +28,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -57,7 +58,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -73,7 +75,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=True,
             theme=None,
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -89,7 +92,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme='readthedocs',
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -105,7 +109,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=True
+            use_directory_urls=True,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -121,7 +126,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=False
+            use_directory_urls=False,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -137,7 +143,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -153,7 +160,8 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -169,7 +177,25 @@ class CLITests(unittest.TestCase):
             config_file=None,
             strict=None,
             theme=None,
-            use_directory_urls=None
+            use_directory_urls=None,
+            watch_theme=False
+        )
+
+    @mock.patch('mkdocs.commands.serve.serve', autospec=True)
+    def test_serve_watch_theme(self, mock_serve):
+
+        result = self.runner.invoke(
+            cli.cli, ["serve", '--watch-theme'], catch_exceptions=False)
+
+        self.assertEqual(result.exit_code, 0)
+        mock_serve.assert_called_once_with(
+            dev_addr=None,
+            livereload='livereload',
+            config_file=None,
+            strict=None,
+            theme=None,
+            use_directory_urls=None,
+            watch_theme=True
         )
 
     @mock.patch('mkdocs.config.load_config', autospec=True)