Use lunr.py for prebuilding indices (mkdocs#1607)

docs/about/release-notes.md

@@ -25,6 +25,16 @@ The current and past members of the MkDocs team.
 
 ### Major Additions to Version 1.1
 
+#### Support for Lunr.py as `prebuild_index` engine
+
+Mkdocs now supports prebuilding indices using [Lunr.py][lunrpy-docs], a pure
+Python implementation of Lunr.js, allowing the user to avoid installing a
+NodeJS environment if so desired. For more information please read the
+[`prebuild_index` documentation][prebuildindex-docs].
+
+[lunrpy-docs]: http://lunr.readthedocs.io/
+[prebuildindex-docs]: ../../user-guide/configuration/#prebuild_index
+
 #### `readthedocs` theme updated with upstream (#588 and #1374)
 
 The `readthedocs` theme now more closely matches the [upstream] Sphinx theme

docs/user-guide/configuration.md

@@ -546,13 +546,23 @@ You may [contribute additional languages].
 
 ##### **prebuild_index**
 
- Optionally generates a pre-built index of all pages, which provides some
- performance improvements for larger sites. Before enabling, check that the
- theme you are using explicitly supports using a prebuilt index (the builtin
- themes do). The pre-build script requires that [Node.js] be installed and the
- command `node` be on the system path. If this feature is enabled and fails for
- any reason, a warning is issued. You may use the `--strict` flag when building
- to cause such a failure to raise an error instead.
+Optionally generates a pre-built index of all pages, which provides some
+performance improvements for larger sites. Before enabling, check that the
+theme you are using explicitly supports using a prebuilt index (the builtin
+themes do).
+
+There are two options for prebuilding the index:
+
+Using [Node.js] setting `prebuild_index` to `True` or `node`. This option
+requires that Node.js be installed and the command `node` be on the system
+path. If this feature is enabled and fails for any reason, a warning is issued.
+You may use the `--strict` flag when building to cause such a failure to raise
+an error instead.
+
+Using [Lunr.py] setting `prebuild_index` to `python`. Lunr.py is installed
+as part of mkdocs and guarantees compatibility with Lunr.js even on languages
+other than english. If you find substantial inconsistencies or problems please
+report it on [Lunr.py's issues] and fall back to the Node.js version.
 
 !!! Note
 
@@ -562,7 +572,7 @@ You may [contribute additional languages].
     the bandwidth increase is relatively small and your users will notice a
     significant improvement in search performance.
 
- **default**: `False`
+**default**: `False`
 
 [custom themes]: custom-themes.md
 [variables that are available]: custom-themes.md#template-variables
@@ -581,3 +591,5 @@ You may [contribute additional languages].
 [Lunr Languages]: https://github.com/MihaiValentin/lunr-languages#lunr-languages-----
 [contribute additional languages]: https://github.com/MihaiValentin/lunr-languages/blob/master/CONTRIBUTING.md
 [Node.js]: https://nodejs.org/
+[Lunr.py]: http://lunr.readthedocs.io/
+[Lunr.py's issues]: https://github.com/yeraydiazdiaz/lunr.py/issues

mkdocs/commands/build.py

@@ -235,6 +235,8 @@ def _build_page(page, config, files, nav, env, dirty=False):
 
 def build(config, live_server=False, dirty=False):
     """ Perform a full site build. """
+    from time import time
+    start = time()
 
     # Run `config` plugin events.
     config = config['plugins'].run_event('config', config)
@@ -300,6 +302,8 @@ def build(config, live_server=False, dirty=False):
     if config['strict'] and utils.warning_filter.count:
         raise SystemExit('\nExited with {} warnings in strict mode.'.format(utils.warning_filter.count))
 
+    log.info('Documentation built in %.2f seconds', time() - start)
+
 
 def site_directory_contains_stale_files(site_directory):
     """ Check if the site directory contains stale files from a previous build. """

mkdocs/config/config_options.py

@@ -159,6 +159,35 @@ def run_validation(self, value):
         raise ValidationError(msg)
 
 
+class Choice(OptionallyRequired):
+    """
+    Choice Config Option
+
+    Validate the config option against a strict set of values.
+    """
+
+    def __init__(self, choices, **kwargs):
+        super(Choice, self).__init__(**kwargs)
+        try:
+            length = len(choices)
+        except TypeError:
+            length = 0
+
+        if not length or isinstance(choices, utils.string_types):
+            raise ValueError('Expected iterable of choices, got {}', choices)
+
+        self.choices = choices
+
+    def run_validation(self, value):
+        if value not in self.choices:
+            msg = ("Expected one of: {0} but received: {1}"
+                   .format(self.choices, value))
+        else:
+            return value
+
+        raise ValidationError(msg)
+
+
 class Deprecated(BaseConfigOption):
 
     def __init__(self, moved_to=None):

mkdocs/contrib/search/__init__.py

@@ -40,7 +40,7 @@ class SearchPlugin(BasePlugin):
     config_scheme = (
         ('lang', LangOption(default=['en'])),
         ('separator', config_options.Type(utils.string_types, default=r'[\s\-]+')),
-        ('prebuild_index', config_options.Type(bool, default=False)),
+        ('prebuild_index', config_options.Choice((False, True, 'node', 'python'), default=False)),
     )
 
     def on_config(self, config, **kwargs):

mkdocs/contrib/search/search_index.py

@@ -7,6 +7,9 @@
 import json
 import logging
 import subprocess
+
+from lunr import lunr
+
 from mkdocs import utils
 
 try:                                    # pragma: no cover
@@ -105,7 +108,7 @@ def generate_search_index(self):
         }
         data = json.dumps(page_dicts, sort_keys=True, separators=(',', ':'))
 
-        if self.config['prebuild_index']:
+        if self.config['prebuild_index'] in (True, 'node'):
             try:
                 script_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'prebuild-index.js')
                 p = subprocess.Popen(
@@ -124,6 +127,12 @@ def generate_search_index(self):
                     log.warning('Failed to pre-build search index. Error: {}'.format(err))
             except (OSError, IOError, ValueError) as e:
                 log.warning('Failed to pre-build search index. Error: {}'.format(e))
+        elif self.config['prebuild_index'] == 'python':
+            idx = lunr(
+                ref='location', fields=('title', 'text'), documents=self._entries,
+                languages=self.config['lang'])
+            page_dicts['index'] = idx.serialize()
+            data = json.dumps(page_dicts, sort_keys=True, separators=(',', ':'))
 
         return data