Deprecate auto-populating extra_css/javascript.

docs/about/release-notes.md

@@ -92,6 +92,20 @@ to support such customization.
 
 [blocks]: ../user-guide/styling-your-docs/#overriding-template-blocks
 
+#### Auto-Populated `extra_css` and `extra_javascript` Deprecated. (#986)
+
+In previous versions of MkDocs, if the `extra_css` or `extra_javascript` config
+settings were empty, MkDocs would scan the `docs_dir` and auto-populate each
+setting with all of the CSS and JavaScript files found. This behavior is
+deprecated and a warning will be issued. In the next release, the auto-populate
+feature will stop working and any unlisted CSS and JavaScript files will not be
+included in the HTML templates. In other words, they will still be copied to the
+`site-dir`, but they will not have any effect on the theme if they are not
+explicitly listed.
+
+All CSS and javaScript files in the `docs_dir` should be explicitly listed in
+the `extra_css` or `extra_javascript` config settings going forward.
+
 #### Support for dirty builds. (#990)
 
 For large sites the build time required to create the pages can become problematic,

docs/user-guide/configuration.md

@@ -221,9 +221,9 @@ directory path.
 
 ### extra_css
 
-Set a list of CSS files to be included by the theme. For example, the
-following example will include the the extra.css file within the css
-subdirectory in your [docs_dir](#docs_dir).
+Set a list of CSS files in your `docs_dir` to be included by the theme. For
+example, the following example will include the the extra.css file within the
+css subdirectory in your [docs_dir](#docs_dir).
 
 ```yaml
 extra_css:
@@ -231,27 +231,23 @@ extra_css:
     - css/second_extra.css
 ```
 
-**default**: By default `extra_css` will contain a list of all the CSS files
-found within the `docs_dir`, if none are found it will be `[]` (an empty list).
+**default**: `[]` (an empty list).
 
 ### extra_javascript
 
-Set a list of JavaScript files to be included by the theme. See the example
-in [extra_css](#extra_css) for usage.
+Set a list of JavaScript files in your `docs_dir` to be included by the theme.
+See the example in [extra_css](#extra_css) for usage.
 
-**default**: By default `extra_javascript` will contain a list of all the
-JavaScript files found within the `docs_dir`, if none are found it will be `[]`
-(an empty list).
+**default**: `[]` (an empty list).
 
 ### extra_templates
 
-Set a list of templates to be built by MkDocs. To see more about writing
-templates for MkDocs read the documentation about [custom themes] and
-specifically the section about the [variables that are available] to templates.
-See the example in [extra_css](#extra_css) for usage.
+Set a list of templates in your `docs_dir` to be built by MkDocs. To see more
+about writing templates for MkDocs read the documentation about [custom themes]
+and specifically the section about the [variables that are available] to
+templates. See the example in [extra_css](#extra_css) for usage.
 
-**default**: Unlike extra_css and extra_javascript, by default `extra_templates`
-will be `[]` (an empty list).
+**default**: `[]` (an empty list).
 
 ### extra
 

mkdocs.yml

@@ -18,6 +18,9 @@ pages:
     - Contributing: about/contributing.md
     - License: about/license.md
 
+extra_css:
+    - css/extra.css
+
 markdown_extensions:
     - toc:
         permalink: 

mkdocs/config/config_options.py

@@ -398,10 +398,10 @@ class Extras(OptionallyRequired):
 
         self.warnings.append((
             'The following files have been automatically included in the '
-            'documentation build and will be added to the HTML: {}. In '
-            'MkDocs they will need to be explicitly included with the '
-            'extra_javascript and extra_css config settings.'
-        ).format(','.join(extras)))
+            'documentation build and will be added to the HTML: {0}. This '
+            'behavior is deprecated. In version 1.0 and later they will '
+            "need to be explicitly listed in the '{1}' config setting."
+        ).format(','.join(extras), key_name))
 
 
 class Pages(Extras):

mkdocs/tests/build_tests.py

@@ -28,6 +28,8 @@ def load_config(cfg=None):
         cfg['site_name'] = 'Example'
     if 'config_file_path' not in cfg:
         cfg['config_file_path'] = os.path.join(os.path.abspath('.'), 'mkdocs.yml')
+    if 'extra_css' not in cfg:
+        cfg['extra_css'] = ['css/extra.css']
     conf = config.Config(schema=config.DEFAULT_SCHEMA)
     conf.load_dict(cfg)
 

mkdocs/tests/config/config_options_tests.py

@@ -289,7 +289,7 @@ class ExtrasTest(unittest.TestCase):
         self.assertRaises(config_options.ValidationError,
                           option.validate, {})
 
-    def test_talk(self):
+    def test_walk(self):
 
         option = config_options.Extras(utils.is_markdown_file)
 

mkdocs/tests/config/config_tests.py

@@ -198,7 +198,6 @@ class ConfigTests(unittest.TestCase):
         )
 
         conf = {
-            'site_name': 'Example',
             'config_file_path': j(os.path.abspath('..'), 'mkdocs.yml')
         }
 
@@ -211,7 +210,11 @@ class ConfigTests(unittest.TestCase):
             c = config.Config(schema=(
                 ('docs_dir', config_options.Dir(default='docs')),
                 ('site_dir', config_options.SiteDir(default='site')),
+                ('config_file_path', config_options.Type(utils.string_types))
             ))
             c.load_dict(patch)
 
-            self.assertRaises(config_options.ValidationError, c.validate)
+            errors, warnings = c.validate()
+
+            self.assertEqual(len(errors), 1)
+            self.assertEqual(warnings, [])