Add --wait flag to serve command.

Fixes #2061.

docs/about/release-notes.md

@@ -25,6 +25,15 @@ The current and past members of the MkDocs team.
 
 ### Major Additions to Version 1.2
 
+#### A `--wait` flag has been added to the `serve` command (#2061)
+
+To delay a rebuild of the site when using the livereload server, use the
+`--wait` flag to specify the number of seconds to wait.
+
+```bash
+mkdocs serve --wait 60
+```
+
 ### Backward Incompatible Changes in 1.2
 
 A theme's files are now excluded from the list of watched files by default

mkdocs/__main__.py

@@ -58,6 +58,7 @@ 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.")
+wait_help = "Wait the specified number of seconds before reloading (default 0)."
 
 
 def add_options(opts):
@@ -125,6 +126,7 @@ def cli():
 @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)
+@click.option('-w', '--wait', help=wait_help, default=0)
 @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, watch_theme):
+def _livereload(host, port, config, builder, site_dir, watch_theme, delay):
 
     # We are importing here for anyone that has issues with livereload. Even if
     # this fails, the --no-livereload alternative should still work.
@@ -66,17 +66,17 @@ def _livereload(host, port, config, builder, site_dir, watch_theme):
     server = LiveReloadServer()
 
     # Watch the documentation files, the config file and the theme files.
-    server.watch(config['docs_dir'], builder)
-    server.watch(config['config_file_path'], builder)
+    server.watch(config['docs_dir'], builder, delay=delay)
+    server.watch(config['config_file_path'], builder, delay=delay)
 
     if watch_theme:
         for d in config['theme'].dirs:
-            server.watch(d, builder)
+            server.watch(d, builder, delay=delay)
 
     # Run `serve` plugin events.
     server = config['plugins'].run_event('serve', server, config=config, builder=builder)
 
-    server.serve(root=site_dir, host=host, port=port, restart_delay=0)
+    server.serve(root=site_dir, host=host, port=port, restart_delay=delay)
 
 
 def _static_server(host, port, site_dir):
@@ -104,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', watch_theme=False, **kwargs):
+          theme_dir=None, livereload='livereload', watch_theme=False, wait=0, **kwargs):
     """
     Start the MkDocs development server
 
@@ -144,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, watch_theme)
+            _livereload(host, port, config, builder, site_dir, watch_theme, delay=wait)
         else:
             _static_server(host, port, site_dir)
     finally:

mkdocs/tests/cli_tests.py

@@ -29,7 +29,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -59,7 +60,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -76,7 +78,8 @@ class CLITests(unittest.TestCase):
             strict=True,
             theme=None,
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -93,7 +96,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme='readthedocs',
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -110,7 +114,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=True,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -127,7 +132,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=False,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -144,7 +150,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -161,7 +168,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -178,7 +186,8 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=None,
-            watch_theme=False
+            watch_theme=False,
+            wait=0
         )
 
     @mock.patch('mkdocs.commands.serve.serve', autospec=True)
@@ -195,7 +204,26 @@ class CLITests(unittest.TestCase):
             strict=None,
             theme=None,
             use_directory_urls=None,
-            watch_theme=True
+            watch_theme=True,
+            wait=0
+        )
+
+    @mock.patch('mkdocs.commands.serve.serve', autospec=True)
+    def test_serve_wait(self, mock_serve):
+
+        result = self.runner.invoke(
+            cli.cli, ["serve", '--wait', '60'], 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=False,
+            wait=60
         )
 
     @mock.patch('mkdocs.config.load_config', autospec=True)