From cc77e9a78685673a902802d28c409008654402f2 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Mon, 13 Oct 2014 13:56:14 +0200 Subject: [PATCH 01/14] Added option clear_site_dir to removed old files from site directory --- mkdocs/build.py | 2 ++ mkdocs/config.py | 4 ++++ mkdocs/utils.py | 15 +++++++++++++++ 3 files changed, 21 insertions(+) diff --git a/mkdocs/build.py b/mkdocs/build.py index 22a91b2e..f3e86692 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -207,6 +207,8 @@ def build(config, live_server=False, dump_json=False): if dump_json: build_pages(config, dump_json=True) else: + if config['clear_site_dir']: + utils.clear_directory(config['site_dir']) utils.copy_media_files(config['theme_dir'], config['site_dir']) utils.copy_media_files(config['docs_dir'], config['site_dir']) build_pages(config) diff --git a/mkdocs/config.py b/mkdocs/config.py index 40781e65..8a8ce83a 100644 --- a/mkdocs/config.py +++ b/mkdocs/config.py @@ -52,6 +52,10 @@ DEFAULT_CONFIG = { # PyMarkdown extension names. 'markdown_extensions': (), + + # Remove the content of site_dir to remove old files which dropped out + # of the documentation + 'clear_site_dir': False, # Determine if the site should generate a json search index and include # search elements in the theme. - TODO diff --git a/mkdocs/utils.py b/mkdocs/utils.py index f60188ba..9ee9d78d 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -33,6 +33,21 @@ def write_file(content, output_path): open(output_path, 'wb').write(content) +def clear_directory(directory): + """ + Remove the content of a directory recursively but not the directory itself. + """ + for entry in os.listdir(directory): + path = os.path.join(directory, entry) + try: + if os.path.isdir(path): + shutil.rmtree(path, True) + else: + os.unlink(path) + except Exception, e: + print e + + def copy_media_files(from_dir, to_dir): """ Recursively copy all files except markdown and HTML into another directory. From 5b99cb1b2397fc75a417a732d695fff32e323e87 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Mon, 13 Oct 2014 15:44:51 +0200 Subject: [PATCH 02/14] Fixed syntax error --- mkdocs/utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs/utils.py b/mkdocs/utils.py index 9ee9d78d..494e474b 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -44,7 +44,7 @@ def clear_directory(directory): shutil.rmtree(path, True) else: os.unlink(path) - except Exception, e: + except Exception as e: print e From dc62ac213c79d9712f366fdaa6355af0836b8928 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Mon, 13 Oct 2014 16:49:49 +0200 Subject: [PATCH 03/14] Fixed another Python 3 syntax error --- mkdocs/utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs/utils.py b/mkdocs/utils.py index 494e474b..8135b1e8 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -45,7 +45,7 @@ def clear_directory(directory): else: os.unlink(path) except Exception as e: - print e + print(e) def copy_media_files(from_dir, to_dir): From dcd90abef6f6be875325c333beef5b5007eb5c49 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Mon, 13 Oct 2014 16:59:23 +0200 Subject: [PATCH 04/14] Fixed whitespace issues reported by flake8 test --- mkdocs/config.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs/config.py b/mkdocs/config.py index 5dc013a8..81fca263 100644 --- a/mkdocs/config.py +++ b/mkdocs/config.py @@ -52,10 +52,10 @@ DEFAULT_CONFIG = { # PyMarkdown extension names. 'markdown_extensions': (), - - # Remove the content of site_dir to remove old files which dropped out + + # Remove the content of site_dir to remove old files which dropped out # of the documentation - 'clear_site_dir': False, + 'clear_site_dir': False, # Determine if the site should generate a json search index and include # search elements in the theme. - TODO From 7ebc019a40529cb98dd07cd777d5fc8f7502caf8 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 14 Oct 2014 10:43:49 +0200 Subject: [PATCH 05/14] Removed clear_site_dir option and made it the default behaviour --- mkdocs/build.py | 5 +++-- mkdocs/config.py | 4 ---- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/mkdocs/build.py b/mkdocs/build.py index f300da6a..cb811577 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -217,8 +217,9 @@ def build(config, live_server=False, dump_json=False): if dump_json: build_pages(config, dump_json=True) else: - if config['clear_site_dir']: - utils.clear_directory(config['site_dir']) + # Clear site_dir to remove old files which dropped out of the documentation + utils.clear_directory(config['site_dir']) + for theme_dir in config['theme_dir']: utils.copy_media_files(theme_dir, config['site_dir']) utils.copy_media_files(config['docs_dir'], config['site_dir']) diff --git a/mkdocs/config.py b/mkdocs/config.py index 81fca263..c50aae7e 100644 --- a/mkdocs/config.py +++ b/mkdocs/config.py @@ -53,10 +53,6 @@ DEFAULT_CONFIG = { # PyMarkdown extension names. 'markdown_extensions': (), - # Remove the content of site_dir to remove old files which dropped out - # of the documentation - 'clear_site_dir': False, - # Determine if the site should generate a json search index and include # search elements in the theme. - TODO 'include_search': False, From 77eada76c4af76ce7bbf991afd343ad3604f0b19 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 14 Oct 2014 10:48:57 +0200 Subject: [PATCH 06/14] Fixed bug in clear_directory (fails if directory does not exist) --- mkdocs/utils.py | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/mkdocs/utils.py b/mkdocs/utils.py index 8135b1e8..008b232b 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -37,15 +37,16 @@ def clear_directory(directory): """ Remove the content of a directory recursively but not the directory itself. """ - for entry in os.listdir(directory): - path = os.path.join(directory, entry) - try: - if os.path.isdir(path): - shutil.rmtree(path, True) - else: - os.unlink(path) - except Exception as e: - print(e) + if os.path.exists(directory): + for entry in os.listdir(directory): + path = os.path.join(directory, entry) + try: + if os.path.isdir(path): + shutil.rmtree(path, True) + else: + os.unlink(path) + except Exception as e: + print(e) def copy_media_files(from_dir, to_dir): From 7bef126d533db54cbfee8f50b4f7de596af223e2 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 14 Oct 2014 15:19:59 +0200 Subject: [PATCH 07/14] Removed exception handling as suggested by d0ugal --- mkdocs/utils.py | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/mkdocs/utils.py b/mkdocs/utils.py index 008b232b..85c51214 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -40,13 +40,10 @@ def clear_directory(directory): if os.path.exists(directory): for entry in os.listdir(directory): path = os.path.join(directory, entry) - try: - if os.path.isdir(path): - shutil.rmtree(path, True) - else: - os.unlink(path) - except Exception as e: - print(e) + if os.path.isdir(path): + shutil.rmtree(path, True) + else: + os.unlink(path) def copy_media_files(from_dir, to_dir): From c7c41dad73ac87ec80220bd12e01172e3c5ed98a Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 14 Oct 2014 15:22:24 +0200 Subject: [PATCH 08/14] Clear directory for json builds as well --- mkdocs/build.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mkdocs/build.py b/mkdocs/build.py index cb811577..21f68286 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -212,14 +212,14 @@ def build(config, live_server=False, dump_json=False): """ Perform a full site build. """ + # Clear site_dir to remove old files which dropped out of the documentation + utils.clear_directory(config['site_dir']) + if not live_server: print("Building documentation to directory: %s" % config['site_dir']) if dump_json: build_pages(config, dump_json=True) else: - # Clear site_dir to remove old files which dropped out of the documentation - utils.clear_directory(config['site_dir']) - for theme_dir in config['theme_dir']: utils.copy_media_files(theme_dir, config['site_dir']) utils.copy_media_files(config['docs_dir'], config['site_dir']) From 02887edd3de70f37b5eaa80976a245d3d5fcfae9 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Wed, 15 Oct 2014 11:26:02 +0200 Subject: [PATCH 09/14] Added --clean switch to build command and output of stale files warning (with simple check) --- mkdocs/build.py | 23 +++++++++++++++++++---- mkdocs/main.py | 5 ++++- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/mkdocs/build.py b/mkdocs/build.py index 21f68286..8c06a4a9 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -208,15 +208,17 @@ 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. """ - # Clear site_dir to remove old files which dropped out of the documentation - utils.clear_directory(config['site_dir']) - + if clean_site_dir: + utils.clear_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: @@ -224,3 +226,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 \ No newline at end of file diff --git a/mkdocs/main.py b/mkdocs/main.py index ae8cdfe2..5c77d3a2 100755 --- a/mkdocs/main.py +++ b/mkdocs/main.py @@ -29,7 +29,10 @@ def main(cmd, args, options=None): serve(config, options=options) elif cmd == 'build': config = load_config(options=options) - build(config) + if 'clean' in options: + build(config, clean_site_dir=True) + else: + build(config) elif cmd == 'json': config = load_config(options=options) build(config, dump_json=True) From a4351e6eb8f2797a08572e44401008a3ffc9b225 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Wed, 15 Oct 2014 11:28:30 +0200 Subject: [PATCH 10/14] Fixed flake8 error (no newline at end of file) --- mkdocs/build.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs/build.py b/mkdocs/build.py index 8c06a4a9..f2282270 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -238,4 +238,4 @@ def site_directory_contains_stale_files(site_directory): if os.path.exists(site_directory): if os.listdir(site_directory): return True - return False \ No newline at end of file + return False From 5d24a5c0c878aec55bdc033eeb3153ab7fa03623 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Wed, 15 Oct 2014 11:54:46 +0200 Subject: [PATCH 11/14] Renamed clear_directory to clean_directory --- mkdocs/build.py | 2 +- mkdocs/utils.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs/build.py b/mkdocs/build.py index f2282270..522c8af6 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -213,7 +213,7 @@ def build(config, live_server=False, dump_json=False, clean_site_dir=False): Perform a full site build. """ if clean_site_dir: - utils.clear_directory(config['site_dir']) + 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']): diff --git a/mkdocs/utils.py b/mkdocs/utils.py index 85c51214..ee04c73a 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -33,7 +33,7 @@ def write_file(content, output_path): open(output_path, 'wb').write(content) -def clear_directory(directory): +def clean_directory(directory): """ Remove the content of a directory recursively but not the directory itself. """ From fa52f6b6ead0d1d50a8efcafeac012c3fc1591ef Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 21 Oct 2014 10:30:54 +0200 Subject: [PATCH 12/14] Enabled clean switch for json and gh-deploy commands as well --- mkdocs/build.py | 1 + mkdocs/main.py | 10 ++++------ 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/mkdocs/build.py b/mkdocs/build.py index 522c8af6..b0ac6833 100644 --- a/mkdocs/build.py +++ b/mkdocs/build.py @@ -213,6 +213,7 @@ 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']) diff --git a/mkdocs/main.py b/mkdocs/main.py index 5c77d3a2..c73bdfac 100755 --- a/mkdocs/main.py +++ b/mkdocs/main.py @@ -24,21 +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) - if 'clean' in options: - build(config, clean_site_dir=True) - else: - 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) From b1ade76ccd0d7344db469aa982e70961be479992 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 21 Oct 2014 10:32:01 +0200 Subject: [PATCH 13/14] Added documentation about new --clean switch --- docs/about/release-notes.md | 2 ++ docs/index.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 1ebf79bd..2ee7f9dd 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -20,6 +20,8 @@ You can determine your currently installed version using `pip freeze`: `mardown_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 diff --git a/docs/index.md b/docs/index.md index c59b23ab..cec7faa3 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. From 40d8a505c683d9dfc5082e81a5fe835bf9d7c9f3 Mon Sep 17 00:00:00 2001 From: Michael Diodone Date: Tue, 21 Oct 2014 10:32:24 +0200 Subject: [PATCH 14/14] Fixed small typos in release notes --- docs/about/release-notes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 2ee7f9dd..3002dac5 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -17,7 +17,7 @@ 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 @@ -26,11 +26,11 @@ You can determine your currently installed version using `pip freeze`: 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