Skip to content
Snippets Groups Projects
Unverified Commit 04b7b654 authored by mmcky's avatar mmcky Committed by GitHub
Browse files

RELEASE: v0.15.1 + BUG: Issue warning for sphinxcontrib-bibtex + docutils>=0.18,<0.20 (#1965)

* pin docutils < 0.18 (https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/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
parent ca7db4e5
No related branches found
Tags v0.15.1
No related merge requests found
# 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))
......
(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}
......
"""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
......
......@@ -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):
......
......@@ -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",
......
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):
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment