Navbar is in the wrong position when using sphinxcontrib-bibtex

[Rémi Delaporte-Mathurin]

Describe the bug

context
When I add a bibliography from sphinxcontrib-bibtex with the sphinx-book-theme, the right navbar is flushed to the bottom and the general layout is messed up.

expectation
This is the expected layout (obtained by removing the bibliography)

Reproduce the bug

This is my conf.py:

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys

sys.path.insert(0, os.path.abspath("../.."))

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "FESTIM"
copyright = "2022, Remi Delaporte-Mathurin"
author = "Remi Delaporte-Mathurin"
release = "v0.10.2"


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.autosectionlabel",
    "sphinx.ext.doctest",
    "sphinx.ext.intersphinx",
    "sphinx.ext.coverage",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinx_design",
    "sphinxcontrib.bibtex",
    "matplotlib.sphinxext.plot_directive",
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


source_suffix = ".rst"

# The master toctree document.
master_doc = "index"

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None


# shorten module names in readme
add_module_names = False

# bibliography file
bibtex_bibfiles = ["bibliography/references.bib"]

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_book_theme"
html_static_path = ["_static"]
html_css_files = ["style.css"]

html_theme_options = {
    "repository_url": "https://github.com/RemDelaporteMathurin/FESTIM",
    "use_repository_button": True,
    "use_edit_page_button": True,
    "repository_branch": "main",
    "path_to_docs": "./docs/source",
}

html_title = "FESTIM"

This is my theory.rst file:

======
Theory
======

--------------
Bulk physics 
--------------

H transport
^^^^^^^^^^^

:cite:`McNabb1963`

----------
References
----------

.. bibliography:: bibliography/references.bib
     :style: unsrt

NOTE: removing the .. bibliography:: call fixes the issue.

List your environment

This is my environment

name: fenics
channels:
  - conda-forge
  - defaults
dependencies:
  - fenics
  - matplotlib==3.7.1
  - pip>=20.1
  - pip:
    - sympy
    - sphinx_book_theme==1.0.1
    - sphinx==6.2.1
    - sphinx-design==0.4.1
    - sphinxcontrib-bibtex

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[Rémi Delaporte-Mathurin]

Not sure if I should (also?) open an issue at https://github.com/mcmtroffaes/sphinxcontrib-bibtex

[Rémi Delaporte-Mathurin]

UPDATE: when forcing the update to sphinx v7 the buggy behaviour is fixed.

pip install sphinx==7.2.6

However, this isn't possible in readthedocs since sphinx-book-theme doesn't support sphinx 7.

https://readthedocs.org/projects/festim/builds/22839915/

[Angus Hollands]

@RemDelaporteMathurin sphinx-book-theme 1.1.0rc1 does support Sphinx 7!

As for the issue reported here, I suspect you might be running into a known docutils bug. Could you identify the version of docutils you have installed (with python -m pip show docutils)?

[Angus Hollands]

Actually, I installed sphinx==6.2.1 and confirmed that this installs the known-broken version of docutils. It's unfortunate that this precludes using Sphinx 6.

[Angus Hollands]

If you really need Sphinx 6 (e.g. to use Jupyter Book CLI tools — we're just updating everything to Sphinx 7), you could monkeypatch docutils in your conf.py and ignore the warnings from sphinxcontrib-bibtex:

import docutils.nodes

def previous_sibling(self):
    """Return preceding sibling node or ``None``."""
    try:
        i = self.parent.index(self)
    except (AttributeError):
        if not self.parent:
            return None
        else:
            index = self.parent.index(self)
            return self.parent[index - 1] if index > 0 else None

docutils.nodes.Element.previous_sibling = previous_sibling

We may end up having to do that ourselves to ensure that JB remains compatible with more versions of Sphinx.

[Rémi Delaporte-Mathurin]

@agoose77 thank you very much!

I tested it and it worked properly!

Solution was simply to upgrade to Sphinx 7 and sphinx-book-theme 1.1.0rc1