From 930ae26a55436f7e1706d6076befb2853c8a0285 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Fri, 26 May 2023 12:39:57 +0200 Subject: [PATCH] New flag `mkdocs serve --clean` - simulate a pure `mkdocs build` and then serve Also rename `--dirtyreload` flag to `--dirty` (keep the old name working) --- docs/user-guide/configuration.md | 2 +- mkdocs/__main__.py | 17 ++++++++++------- mkdocs/commands/serve.py | 13 ++++++++----- mkdocs/plugins.py | 2 +- mkdocs/tests/cli_tests.py | 14 ++++++++++++-- 5 files changed, 32 insertions(+), 16 deletions(-) diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 95574313..7a749ebb 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -310,7 +310,7 @@ exclude_docs: | This follows the [.gitignore pattern format](https://git-scm.com/docs/gitignore#_pattern_format). -Note that `mkdocs serve` does *not* follow this setting and instead displays excluded documents but with a "DRAFT" mark. +Note that `mkdocs serve` does *not* follow this setting and instead displays excluded documents but with a "DRAFT" mark. To prevent this effect, you can run `mkdocs serve --clean`. The following defaults are always implicitly prepended - to exclude dot-files (and directories) as well as the top-level `templates` directory: diff --git a/mkdocs/__main__.py b/mkdocs/__main__.py index 84e7d3f0..a13e9378 100644 --- a/mkdocs/__main__.py +++ b/mkdocs/__main__.py @@ -111,8 +111,9 @@ site_dir_help = "The directory to output the result of the documentation build." use_directory_urls_help = "Use directory URLs when building pages (the default)." reload_help = "Enable the live reloading in the development server (this is the default)" no_reload_help = "Disable the live reloading in the development server." -dirty_reload_help = ( - "Enable the live reloading in the development server, but only re-build files that have changed" +serve_dirty_help = "Only re-build files that have changed." +serve_clean_help = ( + "Build the site without any effects of `mkdocs serve` - pure `mkdocs build`, then serve." ) commit_message_help = ( "A commit message to use when committing to the " @@ -201,7 +202,7 @@ PYTHON_VERSION = f"{sys.version_info.major}.{sys.version_info.minor}" PKG_DIR = os.path.dirname(os.path.abspath(__file__)) -@click.group(context_settings={'help_option_names': ['-h', '--help']}) +@click.group(context_settings=dict(help_option_names=['-h', '--help'], max_content_width=120)) @click.version_option( __version__, '-V', @@ -217,21 +218,23 @@ def cli(): @cli.command(name="serve") @click.option('-a', '--dev-addr', help=dev_addr_help, metavar='') -@click.option('--livereload', 'livereload', flag_value='livereload', help=reload_help, default=True) +@click.option('--livereload', 'livereload', flag_value='livereload', default=True, hidden=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('--dirtyreload', 'build_type', flag_value='dirty', hidden=True) +@click.option('--dirty', 'build_type', flag_value='dirty', help=serve_dirty_help) +@click.option('-c', '--clean', 'build_type', flag_value='clean', help=serve_clean_help) @click.option('--watch-theme', help=watch_theme_help, is_flag=True) @click.option( '-w', '--watch', help=watch_help, type=click.Path(exists=True), multiple=True, default=[] ) @common_config_options @common_options -def serve_command(dev_addr, livereload, watch, **kwargs): +def serve_command(**kwargs): """Run the builtin development server""" from mkdocs.commands import serve _enable_warnings() - serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs) + serve.serve(**kwargs) @cli.command(name="build") diff --git a/mkdocs/commands/serve.py b/mkdocs/commands/serve.py index a21269d2..3c1bb12b 100644 --- a/mkdocs/commands/serve.py +++ b/mkdocs/commands/serve.py @@ -25,6 +25,7 @@ def serve( theme=None, theme_dir=None, livereload='livereload', + build_type=None, watch_theme=False, watch=[], **kwargs, @@ -55,8 +56,8 @@ def serve( **kwargs, ) - live_server = livereload in ('dirty', 'livereload') - dirty = livereload == 'dirty' + is_clean = build_type == 'clean' + is_dirty = build_type == 'dirty' def builder(config: MkDocsConfig | None = None): log.info("Building documentation...") @@ -72,10 +73,12 @@ def serve( # Override a few config settings after validation config.site_url = f'http://{config.dev_addr}{mount_path(config)}' - build(config, live_server=live_server, dirty=dirty) + build(config, live_server=not is_clean, dirty=is_dirty) config = get_config() - config['plugins'].run_event('startup', command='serve', dirty=dirty) + config['plugins'].run_event( + 'startup', command=('build' if is_clean else 'serve'), dirty=is_dirty + ) try: # Perform the initial build @@ -96,7 +99,7 @@ def serve( server.error_handler = error_handler - if live_server: + if livereload: # Watch the documentation files, the config file and the theme files. server.watch(config.docs_dir) server.watch(config.config_file_path) diff --git a/mkdocs/plugins.py b/mkdocs/plugins.py index 7c5ab277..46305c32 100644 --- a/mkdocs/plugins.py +++ b/mkdocs/plugins.py @@ -110,7 +110,7 @@ class BasePlugin(Generic[SomeConfig]): Parameters: command: the command that MkDocs was invoked with, e.g. "serve" for `mkdocs serve`. - dirty: whether `--dirtyreload` or `--dirty` flags were passed. + dirty: whether `--dirty` flag was passed. """ def on_shutdown(self) -> None: diff --git a/mkdocs/tests/cli_tests.py b/mkdocs/tests/cli_tests.py index 67c40d64..ae60991a 100644 --- a/mkdocs/tests/cli_tests.py +++ b/mkdocs/tests/cli_tests.py @@ -22,6 +22,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=None, theme=None, @@ -53,6 +54,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr='0.0.0.0:80', livereload='livereload', + build_type=None, config_file=None, strict=None, theme=None, @@ -69,6 +71,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=True, theme=None, @@ -87,6 +90,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=None, theme='readthedocs', @@ -105,6 +109,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=None, theme=None, @@ -123,6 +128,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=None, theme=None, @@ -139,6 +145,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=None, theme=None, @@ -155,6 +162,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='no-livereload', + build_type=None, config_file=None, strict=None, theme=None, @@ -165,12 +173,13 @@ class CLITests(unittest.TestCase): @mock.patch('mkdocs.commands.serve.serve', autospec=True) def test_serve_dirtyreload(self, mock_serve): - result = self.runner.invoke(cli.cli, ["serve", '--dirtyreload'], catch_exceptions=False) + result = self.runner.invoke(cli.cli, ["serve", '--dirty'], catch_exceptions=False) self.assertEqual(result.exit_code, 0) mock_serve.assert_called_once_with( dev_addr=None, - livereload='dirty', + livereload='livereload', + build_type='dirty', config_file=None, strict=None, theme=None, @@ -187,6 +196,7 @@ class CLITests(unittest.TestCase): mock_serve.assert_called_once_with( dev_addr=None, livereload='livereload', + build_type=None, config_file=None, strict=None, theme=None,