DOC: separate source file for references

spatialaudio · Feb 25, 2023 · 4df8cb3 · 4df8cb3
1 parent 78088ab
commit 4df8cb3
Show file tree

Hide file tree

Showing 4 changed files with 48 additions and 20 deletions.
diff --git a/doc/a-normal-rst-file.rst b/doc/a-normal-rst-file.rst
@@ -215,25 +215,7 @@ You can create a list of references in any reStructuredText file
 
     .. bibliography::
 
-Have a look at the documentation for all the available options.
-
-The list of references may look something like this (in HTML output):
-
-.. bibliography::
-    :style: alpha
-
-However, in the LaTeX/PDF output the list of references will not appear here,
-but at the end of the document.
-For a possible work-around,
-see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156.
-
-.. warning::
-
-    With ``docutils`` versions 0.18 and 0.19,
-    the HTML output after the bibliography is broken,
-    see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309.
-    This problem will be fixed in the next ``docutils`` version
-    (either 0.19.1 or 0.20).
+For an example, see the file ``doc/references.rst``.
 
 
 Footnote citations

diff --git a/doc/conf.py b/doc/conf.py
@@ -173,6 +173,19 @@
 latex_show_urls = 'footnote'
 latex_show_pagerefs = True
 
+# -- Work-around to get LaTeX References at the same place as HTML --------
+
+# See https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156
+
+import sphinx.builders.latex.transforms
+
+class DummyTransform(sphinx.builders.latex.transforms.BibliographyTransform):
+
+    def run(self, **kwargs):
+        pass
+
+sphinx.builders.latex.transforms.BibliographyTransform = DummyTransform
+
 # -- Options for EPUB output ----------------------------------------------
 
 # These are just defined to avoid Sphinx warnings related to EPUB:

diff --git a/doc/index.rst b/doc/index.rst
@@ -3,7 +3,7 @@
 All of the following content
 was generated from Jupyter notebooks,
 except for the sections :doc:`a-normal-rst-file`,
-:doc:`contributing` and :doc:`version-history`,
+:doc:`contributing`, :doc:`references` and :doc:`version-history`,
 which were generated from Sphinx's built-in `reStructuredText`__ format.
 The sections
 :doc:`custom-formats`,
@@ -39,6 +39,7 @@ __ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
     a-markdown-file
     links
     contributing
+    references
     version-history
 
 .. only:: html

diff --git a/doc/references.rst b/doc/references.rst
@@ -0,0 +1,32 @@
+References
+==========
+
+By default, in the LaTeX/PDF output the list of references will not appear here,
+but instead at the end of the document.
+For a possible work-around (which is also used here)
+see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/156.
+
+The list of references may look something like this:
+
+.. raw:: latex
+
+    \begingroup
+    \def\section#1#2{}
+    \def\chapter#1#2{}
+    \begin{thebibliography}{1234}
+
+.. bibliography::
+    :style: alpha
+
+.. raw:: latex
+
+    \end{thebibliography}
+    \endgroup
+
+.. warning::
+
+    With ``docutils`` versions 0.18 and 0.19,
+    the HTML output after the bibliography is broken,
+    see https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309.
+    This problem will be fixed in the next ``docutils`` version
+    (either 0.19.1 or 0.20).