Merge pull request #154 from devbliss/feature/clear-site-directory-option

Clear site directory before build

docs/about/release-notes.md

@@ -17,18 +17,20 @@ You can determine your currently installed version using `pip freeze`:
 
 * Added support for Python 3.3 and 3.4. (#103)
 * Configurable Python-Markdown extensions with the config setting
-  `mardown_extensions`. (#74)
+  `markdown_extensions`. (#74)
 * Added `mkdocs json` command to output your rendered
   documentation as json files. (#128)
+* Added `--clean` switch to `build`, `json` and `gh-deploy` commands to
+  remove stale files from the output directory (#157)
 * Support multiple theme directories to allow replacement of
   individual templates rather than copying the full theme. (#129)
 * Bugfix: Fix issue rendering the table of contents with some
   configs. (#146)
-* Bugfix: Fix path for embeded images in sub pages. (#138)
+* Bugfix: Fix path for embedded images in sub pages. (#138)
 * Bugfix: Fix `use_directory_urls` config behaviour. (#63)
 * Bugfix: Add support for `extra_javascript` and `extra_css` in
   all themes. (#90)
-* Bugfix: Fix path-handling under windows. (#121)
+* Bugfix: Fix path-handling under Windows. (#121)
 * Bugfix: Fix the menu generation in the readthedocstheme. (#110)
 * Bugfix: Fix the mkdocs command creation under Windows. (#122)
 * Bugfix: Correctly handle external files in `extra_javascript` and

docs/index.md

@@ -144,6 +144,10 @@ If you're using source code control such as `git` you probably don't want to che
 
 If you're using another source code control you'll want to check it's documentation on how to ignore specific directories.
 
+After some time, files may be removed from the documentation but they will still reside in the `site` directory. To remove those stale files, just run mkdocs with the `--clean` switch.
+
+    $ mkdocs build --clean
+
 ## Deploying
 
 The documentation site that we've just built only uses static files so you'll be able to host it from pretty much anywhere. [GitHub project pages](https://help.github.com/articles/creating-project-pages-manually) and [Amazon S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) are good hosting options. Upload the contents of the entire `site` directory to wherever you're hosting your website from and you're done.

mkdocs/build.py

@@ -208,12 +208,18 @@ def build_pages(config, dump_json=False):
             utils.write_file(output_content.encode('utf-8'), output_path)
 
 
-def build(config, live_server=False, dump_json=False):
+def build(config, live_server=False, dump_json=False, clean_site_dir=False):
     """
     Perform a full site build.
     """
+    if clean_site_dir:
+        print("Cleaning site directory")
+        utils.clean_directory(config['site_dir'])
     if not live_server:
         print("Building documentation to directory: %s" % config['site_dir'])
+        if not clean_site_dir and site_directory_contains_stale_files(config['site_dir']):
+            print("Directory %s contains stale files. Use --clean to remove them." % config['site_dir'])
+
     if dump_json:
         build_pages(config, dump_json=True)
     else:
@@ -221,3 +227,16 @@ def build(config, live_server=False, dump_json=False):
             utils.copy_media_files(theme_dir, config['site_dir'])
         utils.copy_media_files(config['docs_dir'], config['site_dir'])
         build_pages(config)
+
+
+def site_directory_contains_stale_files(site_directory):
+    """
+    Check if the site directory contains stale files from a previous build.
+    Right now the check returns true if the directory is not empty.
+    A more sophisticated approach should be found to trigger only if there are
+    files that won't be overwritten anyway.
+    """
+    if os.path.exists(site_directory):
+        if os.listdir(site_directory):
+            return True
+    return False

mkdocs/main.py

@@ -24,18 +24,19 @@ def main(cmd, args, options=None):
     """
     Build the documentation, and optionally start the devserver.
     """
+    clean_site_dir = 'clean' in options
     if cmd == 'serve':
         config = load_config(options=options)
         serve(config, options=options)
     elif cmd == 'build':
         config = load_config(options=options)
-        build(config)
+        build(config, clean_site_dir=clean_site_dir)
     elif cmd == 'json':
         config = load_config(options=options)
-        build(config, dump_json=True)
+        build(config, dump_json=True, clean_site_dir=clean_site_dir)
     elif cmd == 'gh-deploy':
         config = load_config(options=options)
-        build(config)
+        build(config, clean_site_dir=clean_site_dir)
         gh_deploy(config)
     elif cmd == 'new':
         new(args, options)

mkdocs/utils.py

@@ -33,6 +33,19 @@ def write_file(content, output_path):
     open(output_path, 'wb').write(content)
 
 
+def clean_directory(directory):
+    """
+    Remove the content of a directory recursively but not the directory itself.
+    """
+    if os.path.exists(directory):
+        for entry in os.listdir(directory):
+            path = os.path.join(directory, entry)
+            if os.path.isdir(path):
+                shutil.rmtree(path, True)
+            else:
+                os.unlink(path)
+
+
 def copy_media_files(from_dir, to_dir):
     """
     Recursively copy all files except markdown and HTML into another directory.