IMPROVE: Enable local_extensions to be specified in _config.yml (#1102)

docs/advanced/sphinx.md

@@ -137,46 +137,8 @@ int main() {
 
 ### Local Sphinx Extensions
 
-[Sphinx is able to use local extensions](https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html#using-the-extension) by adding additional directories to the [Python path](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH). At present, this functionality is not available within Jupyter Book.
-
-However, you can use a local Sphinx extension by using `pip` and installing the package locally. Below we'll document how you can create a local `pip`-installable Sphinx extension.
-
-First, write a minimal `setup.py` as follows:
-
-```python
-from setuptools import setup
-
-setup(
-	name='my_sphinx_ext'
-)
-```
-
-```{seealso}
-For further documentation on the purposes and configuration of `setup.py`, please refer to [the official Python documentation on setup scripts](https://docs.python.org/3/distutils/setupscript.html).
-```
-
-Next, create a new directory with your extension's name (in this case `my_sphinx_ext`) within the same directory as `setup.py`. Afterwards, create an *empty* file called `__init__.py` within this directory. If you are on Linux, simply `touch my_sphinx_ext/__init__.py`. The result should be:
-
-```
-setup.py
-my_sphinx_ext/
-└──__init__.py
-```
-
-Then, execute `pip install -e .` within the directory containing `setup.py`. This will install `my_sphinx_ext` as a local Python package.
-
-It's then as easy as updating your `_config.yml` with your new extension:
-
-```yaml
-  sphinx:
-    extra_extensions:
-    - my_sphinx_ext
-```
-
-
-:::{admonition,tip} More information on creating Sphinx extensions
-The extension in this example is `pip`-installable, but does nothing! For more information about how to create your own Sphinx extension, try following [Sphinx's extension tutorials](https://www.sphinx-doc.org/en/master/development/tutorials/index.html).
-:::
+[Sphinx is able to use local extensions](https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html#using-the-extension) by adding additional directories to the [Python path](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH). You can use local extensions by
+specifying them as [local_extensions](config:sphinx:local_extensions) in the `_config.yml` file.
 
 (custom-assets)=
 ## Custom CSS or JavaScript

docs/customize/config.md

@@ -106,10 +106,13 @@ html:
 ```
 
 (config:sphinx)=
-### Advanced configuration (with sphinx)
+## Advanced configuration (with sphinx)
 
 Users who are familiar with [Sphinx configuration](sphinx:build-config) may wish to directly add extensions or set options to parse to the underlying Sphinx application.
 
+(config:sphinx:extra_extensions)=
+### Adding Extra Extensions
+
 To add extensions, use:
 
 ```yaml
@@ -119,6 +122,22 @@ sphinx:
 
 This will **append** to the list of extensions already loaded by Jupyter Book.
 
+(config:sphinx:local_extensions)=
+### Adding Local Extensions
+
+To add a local extension that requires a path, use:
+
+```yaml
+sphinx:
+  local_extensions:
+    <name>: <path>
+```
+
+This will **append to the list of extensions already loaded by Jupyter Book and update the `sys.path` so
+the local extension can be found.
+
+### Specifying Sphinx Configuration Values
+
 To set additional Sphinx configurations:
 
 ```yaml

jupyter_book/config.py

@@ -6,6 +6,8 @@ from typing import Optional, Union
 
 import jsonschema
 import yaml
+import sys
+import os
 
 from .utils import _message_box
 
@@ -283,6 +285,16 @@ def yaml_to_sphinx(yaml: dict):
             if extension not in sphinx_config["extensions"]:
                 sphinx_config["extensions"].append(extension)
 
+    local_extensions = yaml.get("sphinx", {}).get("local_extensions")
+    if local_extensions:
+        if "extensions" not in sphinx_config:
+            sphinx_config["extensions"] = get_default_sphinx_config()["extensions"]
+        for extension, path in local_extensions.items():
+            if extension not in sphinx_config["extensions"]:
+                sphinx_config["extensions"].append(extension)
+            if path not in sys.path:
+                sys.path.append(os.path.abspath(path))
+
     # items in sphinx.config will override defaults,
     # rather than recursively updating them
     return sphinx_config, yaml.get("sphinx", {}).get("config") or {}

jupyter_book/config_schema.json

@@ -190,6 +190,12 @@
                         "type": "string"
                     }
                 },
+                "local_extensions": {
+                    "type": [
+                        "null",
+                        "object"
+                    ]
+                },
                 "config": {
                     "type": [
                         "null",

jupyter_book/default_config.yml

@@ -69,4 +69,5 @@ repository:
 # Advanced and power-user settings
 sphinx:
   extra_extensions          :   # A list of extra extensions to load by Sphinx (added to those already used by JB).
+  local_extensions          :   # A list of local extensions to load by sphinx specified by "name: path" items
   config                    :   # key-value pairs to directly over-ride the Sphinx configuration

tests/test_config.py

@@ -20,6 +20,7 @@ from jupyter_book.commands import sphinx
         {
             "sphinx": {
                 "extra_extensions": ["other"],
+                "local_extensions": {"helloworld": "./ext"},
                 "config": {
                     "html_theme_options": {
                         "launch_buttons": {"binderhub_url": "other"}

tests/test_config/test_get_final_config_sphinx_.yml

@@ -8,6 +8,8 @@ _user_config:
       new: value
     extra_extensions:
     - other
+    local_extensions:
+      helloworld: ./ext
 final:
   author: The Jupyter Book community
   comments_config:
@@ -35,6 +37,7 @@ final:
   - sphinx_panels
   - sphinx_book_theme
   - other
+  - helloworld
   html_add_permalinks: ¶
   html_baseurl: ''
   html_favicon: ''