From 4a532be1f0fd5d6fe5288d8face4ca835c35a61d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 3 Jul 2015 09:29:07 +0100 Subject: [PATCH] Deprecate include_nav and include_next_previous. Fixes #679 and #681. --- docs/about/release-notes.md | 32 ++++++++++++++----- docs/user-guide/custom-themes.md | 4 --- mkdocs/commands/build.py | 31 ++++++++++-------- mkdocs/config/config_options.py | 10 ++++++ mkdocs/config/defaults.py | 1 + mkdocs/nav.py | 3 ++ .../integration/complicated_config/mkdocs.yml | 2 -- mkdocs/themes/mkdocs/nav.html | 6 ++-- 8 files changed, 58 insertions(+), 31 deletions(-) diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index e52abf87..c2331fc1 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -27,19 +27,15 @@ The current and past members of the MkDocs team. #### Template variables refactored. (#874) +##### Page Context + Page specific variable names in the template context have been refactored as defined in [Custom Themes](../user-guide/custom-themes/#page). The old variable names will issue a warning but continue to work for version 0.16, but may be removed in a future version. -No global variables were altered except `page_description`. Previously -its value was altered programicaly based on whether the current -page was the homepage. Now it simply maps to `config['site_description']`. -Use `page.is_homepage` in the template to conditionally change the -description. - -Any of the following old variables should be updated to the new ones in user -created and third-party templates: +Any of the following old page variables should be updated to the new ones in +user created and third-party templates: | Old Variable Name | New Variable Name | | ----------------- | ------------------- | @@ -61,6 +57,26 @@ created and third-party templates: [page.previous_page]: ../user-guide/custom-themes/#pageprevious_page [page.next_page]: ../user-guide/custom-themes/#pagenext_page +##### Global Context + +Additionaly, a number of global variables have been altered and/or deprecated +and user created and third-party templates should be updated as outlined below: + +Previously, the global variable `include_nav` was altered programicaly based on +the number of pages in the nav. The variable will issue a warning but continue +to work for version 0.16, but may be removed in a future version. Use +`{% if nav|length>1 %}` instead. + +Previously, the global variable `include_next_prev` was altered programicaly +based on the number of pages in the nav. The variable will issue a warning but +continue to work for version 0.16, but may be removed in a future version. Use +`{% if page.next_page or page.previous_page %}` instead. + +Previously the global variable `page_description` was altered programicaly +based on whether the current page was the homepage. Now it simply maps to +`config['site_description']`. Use `{% if page.is_homepage %}` in the template to +conditionally change the description. + #### Increased Template Customization. (#607) The built-in themes have been updated by having each of their many parts wrapped diff --git a/docs/user-guide/custom-themes.md b/docs/user-guide/custom-themes.md index 10df837a..f602f71c 100644 --- a/docs/user-guide/custom-themes.md +++ b/docs/user-guide/custom-themes.md @@ -122,8 +122,6 @@ site_url | [site_url] | extra_css | [extra_css] | extra_javascript | [extra_javascript] | extra | [extra] | -include_nav | [include_nav] | -include_next_prev | [include_next_prev] | copyright | [copyright] | google_analytics | [google_analytics] | @@ -137,8 +135,6 @@ google_analytics | [google_analytics] | [extra_css]: ./configuration.md#extra_css [extra_javascript]: ./configuration.md#extra_javascript [extra]: ./configuration.md#extra -[include_nav]: ./configuration.md#include_nav -[include_next_prev]: ./configuration.md#include_next_prev [copyright]: ./configuration.md#copyright [google_analytics]: ./configuration.md#google_analytics diff --git a/mkdocs/commands/build.py b/mkdocs/commands/build.py index 71f5e551..e0ae9a2d 100644 --- a/mkdocs/commands/build.py +++ b/mkdocs/commands/build.py @@ -269,25 +269,28 @@ def build_pages(config, dump_json=False, dirty=False): # TODO: remove DeprecationContext in v1.0 when all deprecated vars have been removed from jinja2.runtime import Context - deprecated_vars = [ - 'page_title', - 'content', - 'toc', - 'meta', - 'current_page', - 'canonical_url', - 'previous_page', - 'next_page' - ] + deprecated_vars = { + 'page_title': 'page.title', + 'content': 'page.content', + 'toc': 'page.toc', + 'meta': 'page.meta', + 'current_page': 'page.current_page', + 'canonical_url': 'page.canonical_url', + 'previous_page': 'page.previous_page', + 'next_page': 'page.next_page', + 'current_page': 'page', + 'include_nav': 'nav|length>1', + 'include_next_prev': "(page.next_page or page.previous_page)" + } class DeprecationContext(Context): def resolve(self, key): - """ Log a warning when acessing any deprecated variable name. """ + """ Log a warning when accessing any deprecated variable name. """ if key in deprecated_vars: - replacement = "page" if key == 'current_page' else "page.{0}".format(key) log.warn( - "Template variable warning: '{0}' is being deprecated and will not be " - "available in a future version. Use '{1}' instead.".format(key, replacement) + "Template variable warning: '{0}' is being deprecated " + "and will not be available in a future version. Use " + "'{1}' instead.".format(key, deprecated_vars[key]) ) return super(DeprecationContext, self).resolve(key) diff --git a/mkdocs/config/config_options.py b/mkdocs/config/config_options.py index 78ea5455..3e7e2073 100644 --- a/mkdocs/config/config_options.py +++ b/mkdocs/config/config_options.py @@ -468,6 +468,16 @@ class NumPages(OptionallyRequired): super(NumPages, self).__init__(**kwargs) self.at_lest = at_lest + def pre_validation(self, config, key_name): + # TODO: delete deprecated `NumPages` class in version 1.0 + # Numpages is only used by `include_nav` and `include_next_prev`, + # which are both deprecated, so we can delete the entire Option type. + if config.get(key_name) is not None: + # Only issue warning if option is defined by user. + warning = ('The configuration option {0} has been deprecated and will ' + 'be removed in a future release of MkDocs.').format(key_name) + self.warnings.append(warning) + def post_validation(self, config, key_name): if config[key_name] is not None: diff --git a/mkdocs/config/defaults.py b/mkdocs/config/defaults.py index a5ff9d77..14d6544e 100644 --- a/mkdocs/config/defaults.py +++ b/mkdocs/config/defaults.py @@ -92,6 +92,7 @@ DEFAULT_SCHEMA = ( # Jinja2 and the global context. ('extra_templates', config_options.Extras()), + # TODO: delete deprecated `include_nav` and `include_next_previous` in version 1.0 # Determine if the site should include the nav and next/prev elements. # Default, True if the site has more than one page, False otherwise. ('include_nav', config_options.NumPages()), diff --git a/mkdocs/nav.py b/mkdocs/nav.py index 707375e7..c262ffb2 100644 --- a/mkdocs/nav.py +++ b/mkdocs/nav.py @@ -41,6 +41,9 @@ class SiteNavigation(object): def __iter__(self): return iter(self.nav_items) + def __len__(self): + return len(self.nav_items) + def walk_pages(self): """ Returns each page in the site in turn. diff --git a/mkdocs/tests/integration/complicated_config/mkdocs.yml b/mkdocs/tests/integration/complicated_config/mkdocs.yml index b42f736a..ddfc71e4 100644 --- a/mkdocs/tests/integration/complicated_config/mkdocs.yml +++ b/mkdocs/tests/integration/complicated_config/mkdocs.yml @@ -31,8 +31,6 @@ extra_javascript: ["tweak.js", ] extra_templates: ["custom.html", ] -include_nav: true -include_next_prev: false markdown_extensions: - toc: diff --git a/mkdocs/themes/mkdocs/nav.html b/mkdocs/themes/mkdocs/nav.html index bf3a8e77..bbc8ad9e 100644 --- a/mkdocs/themes/mkdocs/nav.html +++ b/mkdocs/themes/mkdocs/nav.html @@ -3,7 +3,7 @@
- {%- if include_nav or include_next_prev or repo_url %} + {%- if nav|length>1 or (page and (page.next_page or page.previous_page)) or repo_url %}