RELEASE: v0.15.1 + BUG: Issue warning for sphinxcontrib-bibtex + docu…

…tils>=0.18,<0.20 (#1965)

* pin docutils < 0.18 (mcmtroffaes/sphinxcontrib-bibtex#322)

* Prep for v0.15.1

* rework, issue warning rather than force version pin on docutils

* only test html if no warnings

* doc: add entry for citations page

* update changelog

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))

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}

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

jupyter_book/config.py

@@ -5,12 +5,16 @@
 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):

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",

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):