diff --git a/CHANGELOG.md b/CHANGELOG.md
index c264732fa1daa37252e3bd4c30495dc9eccf68b2..43a8c6fe7b179264b813a8bb7645e4bf72a9d56d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,19 @@
# Change Log
+## v0.15.1 - 2023-03-13
+
+([full changelog](https://github.com/executablebooks/jupyter-book/compare/v0.15.0...aa0eedbc40691b5f0ea0dd5e80fdfb572e0ee91d))
+
+### Bug
+
+This release is a minor update to alert users of `jupyter-book` to [sphinxcontrib-bibtex #322](https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/322) when building bibliographies with `docutils>=0.18,<0.20` installed.
+
+- [#1965](https://github.com/executablebooks/jupyter-book/pull/1965)
+
+**Bug:** Using `docutils>=0.18` results in breaking the page `html` layout when using `sphinx-book-theme` on pages
+that include a `bibliography` directive.
+
+
## v0.15.0 - 2023-03-07
([full changelog](https://github.com/executablebooks/jupyter-book/compare/v0.14.0...c0d3d0c640a709f84c23ef58b25c65d2e5a6e816))
diff --git a/docs/content/citations.md b/docs/content/citations.md
index dbd9f9a62ac92c6fee1d22e0b3e959785c096feb..c56d85530411279c6ed833e4f6c275c132b9c7b0 100644
--- a/docs/content/citations.md
+++ b/docs/content/citations.md
@@ -1,6 +1,19 @@
(content:citations)=
# Citations and bibliographies
+:::{warning}
+If you are using `docutils<=0.18,<20` then the page containing the `bibliography` directive
+will not have the correct layout. While `docutils` is patched we recommend using `docutils==0.17.1`
+which can be installed by:
+
+```bash
+pip install docutils==0.17.1
+```
+
+This is due to [this issue](https://sourceforge.net/p/docutils/patches/195/)
+:::
+
+
You can add citations and bibliographies using references that are stored in a `bibtex` file that is in your book's folder. You can then add a citation in-line in your Markdown with the `{cite}` role, and include the bibliography from your bibtex file with the `{bibliography}` directive.
```{seealso}
diff --git a/jupyter_book/__init__.py b/jupyter_book/__init__.py
index 6106b334bc4687dd571cab04a89a832918c9d019..e3755175606827421ee5ac31c7ea1faa7419e299 100644
--- a/jupyter_book/__init__.py
+++ b/jupyter_book/__init__.py
@@ -1,6 +1,6 @@
"""Build a book with Jupyter Notebooks and Sphinx."""
-__version__ = "0.15.0"
+__version__ = "0.15.1"
# We connect this function to the step after the builder is initialized
diff --git a/jupyter_book/config.py b/jupyter_book/config.py
index c8dca9179d7a8a10d21e63014e5ec3cc683541e6..1c7389c8f0dcb91ef3ef6abb1249dc27d4a55762 100644
--- a/jupyter_book/config.py
+++ b/jupyter_book/config.py
@@ -5,12 +5,16 @@ from functools import lru_cache
from pathlib import Path
from typing import Optional, Union
+import docutils
import jsonschema
import sphinx
import yaml
+from sphinx.util import logging
from .utils import _message_box
+logger = logging.getLogger(__name__)
+
# Transform a "Jupyter Book" YAML configuration file into a Sphinx configuration file.
# This is so that we can choose more user-friendly words for things than Sphinx uses.
# e.g., 'logo' instead of 'html_logo'.
@@ -408,12 +412,26 @@ def yaml_to_sphinx(yaml: dict):
# Citations
sphinxcontrib_bibtex_configs = ["bibtex_bibfiles", "bibtex_reference_style"]
- if any(ii in yaml for ii in sphinxcontrib_bibtex_configs):
+ if any(bibtex_config in yaml for bibtex_config in sphinxcontrib_bibtex_configs):
# Load sphincontrib-bibtex
if "extensions" not in sphinx_config:
sphinx_config["extensions"] = get_default_sphinx_config()["extensions"]
sphinx_config["extensions"].append("sphinxcontrib.bibtex")
+ # Report Bug in Specific Docutils Versions
+ # TODO: Remove when docutils>=0.20 is pinned in jupyter-book
+ # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/322
+ if (0, 18) <= docutils.__version_info__ < (0, 20):
+ logger.warn(
+ "[sphinxcontrib-bibtex] Beware that docutils versions 0.18 and 0.19 "
+ "(you are running {}) are known to generate invalid html for citations. "
+ "If this issue affects you, please use docutils<0.18 (or >=0.20 once released) "
+ "instead. "
+ "For more details, see https://sourceforge.net/p/docutils/patches/195/".format(
+ docutils.__version__
+ )
+ )
+
# Pass through configuration
if yaml.get("bibtex_bibfiles"):
if isinstance(yaml.get("bibtex_bibfiles"), str):
diff --git a/pyproject.toml b/pyproject.toml
index ad16ddb8ab4571146c81c345d5f174eb09be3e4c..91b231cc112158b48997909bc6b259a51a809928 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -29,7 +29,7 @@ dynamic = ["description", "version"]
requires-python = ">=3.7"
dependencies = [
"click>=7.1,<9",
- "docutils>=0.15,<0.19",
+ "docutils>=0.15,<0.19", # report issue for >=0.18,<0.20 until https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/322 is fixed
"Jinja2",
"jsonschema<5",
"linkify-it-py~=2.0.0",
diff --git a/tests/test_build.py b/tests/test_build.py
index ed4403fd107e12fa497501df4a76d460cb4a77f0..bc352dd7788fb4694895769c7800e0869f9eebd7 100644
--- a/tests/test_build.py
+++ b/tests/test_build.py
@@ -1,5 +1,6 @@
from pathlib import Path
+import docutils
import pytest
import sphinx
from bs4 import BeautifulSoup
@@ -73,10 +74,15 @@ def test_build_singlehtml_from_template(temp_with_override, cli):
build_result = cli.invoke(
commands.build, [book.as_posix(), "-n", "-W", "--builder", "singlehtml"]
)
- assert build_result.exit_code == 0, build_result.output
- html = book.joinpath("_build", "singlehtml")
- assert html.joinpath("index.html").exists()
- assert html.joinpath("intro.html").exists()
+ # TODO: Remove when docutils>=0.20 is pinned in jupyter-book
+ # https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/322
+ if (0, 18) <= docutils.__version_info__ < (0, 20):
+ assert build_result.exit_code == 1, build_result.output
+ else:
+ assert build_result.exit_code == 0, build_result.output
+ html = book.joinpath("_build", "singlehtml")
+ assert html.joinpath("index.html").exists()
+ assert html.joinpath("intro.html").exists()
def test_custom_config(cli, build_resources):