Fix hot-reload and add -w --no-livereload

Closes #9

Author: pedro-psb

src/pulp_docs/cli.py

@@ -8,6 +8,7 @@
 import subprocess
 import sys
 import tempfile
+import typing as t
 from pathlib import Path
 
 import click
@@ -69,6 +70,13 @@ def main(config: Config, verbose: bool):
     config.verbose = verbose
 
 
+# mkdocs help wrapper
+watch_help = (
+    "A directory or file to watch for live reloading. Can be supplied multiple times."
+)
+no_reload_help = "Disable the live reloading in the development server."
+
+
 @main.command()
 @click.option(
     "--clear-cache",
@@ -77,17 +85,40 @@ def main(config: Config, verbose: bool):
     help="Whether to clear the cache before serving (default=False).",
 )
 @click.option("--verbose", "-v", is_flag=True)
+@click.option(
+    "-w",
+    "--watch",
+    help=watch_help,
+    type=click.Path(exists=True),
+    multiple=True,
+    default=[],
+)
+@click.option("--no-livereload", "livereload", flag_value=False, help=no_reload_help)
+@click.option("--livereload", "livereload", flag_value=True, default=True, hidden=True)
 @pass_config
-def serve(config: Config, clear_cache: bool, verbose: bool):
+def serve(
+    config: Config,
+    clear_cache: bool,
+    verbose: bool,
+    watch: t.List[Path],
+    livereload: bool,
+):
     """Run mkdocs server."""
     env = os.environ.copy()
     config.clear_cache = clear_cache
     config.verbose = verbose
     env.update(config.get_environ_dict())
 
-    options = (("--config-file", config.mkdocs_file),)
-    cmd = ["mkdocs", "serve"]
+    watch_list = [("--watch", watched) for watched in watch]
+    flag_list = []
+    if livereload is False:
+        flag_list.append(("--no-livereload",))
 
+    options: t.List[tuple] = [("--config-file", config.mkdocs_file)]
+    options.extend(watch_list)
+    options.extend(flag_list)
+
+    cmd = ["mkdocs", "serve"]
     for opt in options:
         cmd.extend(opt)
     print("Running:", " ".join(str(s) for s in cmd))

src/pulp_docs/data/mkdocs.yml

@@ -36,6 +36,8 @@ theme:
         icon: material/toggle-switch
         name: Switch to light mode    
 
+hooks:
+  - '../mkdocs_hooks.py'
 plugins:
   - search
   - site-urls

src/pulp_docs/mkdocs_hooks.py

@@ -0,0 +1,18 @@
+"""
+Hooks for mkdocs events.
+
+See: https://www.mkdocs.org/user-guide/configuration/#hooks
+"""
+
+
+def on_serve(server, config, builder):
+    """
+    Hook to unwatch the temp dirs.
+
+    See: https://www.mkdocs.org/dev-guide/plugins/#on_serve
+    """
+    tmpdir = config["docs_dir"]
+    mkdocs_yml = config["config_file_path"]
+    server.unwatch(tmpdir)
+    server.unwatch(mkdocs_yml)
+    return server

src/pulp_docs/mkdocs_macros.py

@@ -273,7 +273,11 @@ def define_env(env):
     # Workaround for making "pulpcore/cli/common" from pulp-cli be available as:
     # '::: pulpcore.cli.common' (from any markdown)
     # This should be a general solution.
-    shutil.copytree(source_dir / "pulp-cli/pulpcore", source_dir / "pulpcore/pulpcore", dirs_exist_ok=True)
+    shutil.copytree(
+        source_dir / "pulp-cli/pulpcore",
+        source_dir / "pulpcore/pulpcore",
+        dirs_exist_ok=True,
+    )
     Path(source_dir / "pulpcore/pulpcore/cli/__init__.py").touch(exist_ok=True)
     Path(source_dir / "pulpcore/pulpcore/cli/common/__init__.py").touch(exist_ok=True)
 
@@ -286,6 +290,12 @@ def define_env(env):
     env.conf["docs_dir"] = docs_dir
     env.conf["nav"] = get_navigation(docs_dir, repos)
 
+    # Try to watch CWD/staging_docs
+    watched_workdir = Path("staging_docs")
+    if watched_workdir.exists():
+        env.conf["watch"].append(str(watched_workdir.resolve()))
+
+    # Pass relevant data for future processing
     log.info("[pulp-docs] Done with pulp-docs.")
     env.conf["pulp_repos"] = repos
     env.config["pulp_repos"] = repos