diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 1ebf79bd..3002dac5 100644 --- a/docs/about/release-notes.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index 65b5f1a5..319d8522 100644 --- a/docs/index.md +++ b/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. diff --git a/mkdocs/build.py b/mkdocs/build.py index 3869eb31..b0ac6833 100644 --- a/mkdocs/build.py +++ b/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 diff --git a/mkdocs/main.py b/mkdocs/main.py index ae8cdfe2..c73bdfac 100755 --- a/mkdocs/main.py +++ b/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) diff --git a/mkdocs/utils.py b/mkdocs/utils.py index f60188ba..ee04c73a 100644 --- a/mkdocs/utils.py +++ b/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.