From ad7dda30d651f259304a2efdcc84519ae6542bb7 Mon Sep 17 00:00:00 2001
From: Clément Pit-Claudel
Date: Tue, 4 Sep 2018 18:11:40 -0400
Subject: [doc] Explain why zebibliography needs to be separate and oddly-named

---
 doc/sphinx/zebibliography.rst | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/sphinx/zebibliography.rst b/doc/sphinx/zebibliography.rst
index 0000caa301..756edd5482 100644
--- a/doc/sphinx/zebibliography.rst
+++ b/doc/sphinx/zebibliography.rst
@@ -1,8 +1,17 @@
+.. There are multiple issues with sphinxcontrib-bibtex that we have to work around:
+   - The list of cited entries is computed right after encountering
+     `.. bibliography`, so the file containing that command has to come last
+     alphabetically:
+     https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#unresolved-citations-across-documents
+   - `.. bibliography::` puts the bibliography on its own page with its own
+     title in LaTeX, but includes it inline without a title in HTML:
+     https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#mismatch-between-output-of-html-and-latex-backends
+
 .. _bibliography:
 
-============
-Bibliography
-============
+==============
+ Bibliography
+==============
 
 .. bibliography:: biblio.bib
    :cited:
-- 
cgit v1.2.3