Fix documentation, remove version cap on sphinxcontrib-bibtex (#523)

* remove version constraint on sphinxcontrib-bibtex * add path to .bib file to conf.py * remove html4 writer, since its deprecated with newer sphinx versions * updated mathjax path * fix bug for math formulas with sphinx 5.3.0 * remove version cap for sphinx * fix mathjax output by specifying mathjax as html math renderer * undo changes for mathjax, this will be a separate PR * change citation style to author-year * changed bibliography style for spade, removed labelprefix * define default style for bibliography * remove style for bibliography in spade.rst * add bibtex_reference_style for citations with round brackets * add bibliography style, author_year * bibliography style spade.rst * bibliography style cubic.rst * bibliography style cell_assembly_detection.rst * bibliography style citation.rst * bibliography style contribute.rst * bibliography style _spike_train_processing.rst * remove path to .bib file * bibliography style asset.rst * bibliography style causality.rst * bibliography style change_point_detection.rst * bibliography style gpfa.rst * bibliography style signal_processing.rst * bibliography style spike_train_surrogates.rst * bibliography style unitary_event_analysis.rst * bibliography style waveform_features.rst * bibliography style spike_train_generation.py * bibliography style statistics.py * trigger CI build * add gcc 12 to docs runner * add conda update * install libstdcxx * add activate base environment commands to conda docs runner * Update CI.yml change path to chache * remove version constraint on libstdcxx-ng
NeuralEnsemble · Feb 16, 2023 · 86e5d7b · 86e5d7b
1 parent 0896873
commit 86e5d7b
Show file tree

Hide file tree

Showing 19 changed files with 105 additions and 84 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -389,27 +389,29 @@ jobs:
 
       - name: Install dependencies
         run: |
+          conda config --add channels conda-forge # bugfix with scipy==1.8.1: libstdcxx-ng 12.1.0 required
           sudo apt-get update
           sudo apt install -y libopenmpi-dev openmpi-bin
+          conda update conda
+          conda install -c conda-forge openmpi pandoc libstdcxx-ng # fix libstdc++.so.6: version for new scipy versions > 1.9.1
+          conda env update --file requirements/environment-docs.yml --name base
+          activate base
           python -m pip install --upgrade pip
           pip install -r requirements/requirements-docs.txt
           pip install -r requirements/requirements-tutorials.txt
-          conda config --add channels conda-forge # bugfix with scipy==1.8.1: libstdcxx-ng 12.1.0 required
-          conda update conda
-          conda env update --file requirements/environment-docs.yml --name base
-          conda install -c conda-forge openmpi
-          conda install -c conda-forge pandoc
           pip install -e .[extras]
           # run notebooks
           sed -i -E "s/nbsphinx_execute *=.*/nbsphinx_execute = 'always'/g" doc/conf.py
 
       - name: List packages
         run: |
+          activate base
           pip list
           conda list
           python --version
 
       - name: make html
         run: |
+          activate base
           cd doc
           make html
diff --git a/doc/citation.rst b/doc/citation.rst
@@ -36,7 +36,5 @@ Further publications directly related to Elephant development
 `BibTex references <https://github.com/NeuralEnsemble/elephant/blob/master/doc/bib/elephant.bib>`_
 used in Elephant documentation).
 
-.. bibliography:: bib/elephant.bib
-   :labelprefix: ref
-   :keyprefix: citations-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: citations-
diff --git a/doc/conf.py b/doc/conf.py
@@ -212,11 +212,14 @@
 # see here https://github.com/phn/pytpm/issues/3#issuecomment-12133978
 numpydoc_show_class_members = False
 
-# A fix for Alabaster theme for no space between a citation reference
-# and citation text
-# https://github.com/sphinx-doc/sphinx/issues/6705#issuecomment-536197438
-html4_writer = True
+# path to bibtex-bibfiles.
+bibtex_bibfiles = ['bib/elephant.bib']
 
+# To configure your referencing style:
+bibtex_reference_style = 'author_year_round'
+
+# To configure the bibliography style:
+bibtex_default_style = 'author_year'
 
 # -- Options for LaTeX output --------------------------------------------
 
@@ -349,10 +352,10 @@
 # The name of math_renderer extension for HTML output.
 html_math_renderer = 'mathjax'
 
-# Remove the copyright notice from docstrings:
-
 
 def process_docstring_remove_copyright(app, what, name, obj, options, lines):
+    """Remove the copyright notice from docstrings: """
+
     copyright_line = None
     for i, line in enumerate(lines):
         if line.startswith(':copyright:'):
@@ -366,3 +369,56 @@ def process_docstring_remove_copyright(app, what, name, obj, options, lines):
 def setup(app):
     app.connect('autodoc-process-docstring',
                 process_docstring_remove_copyright)
+
+# replace square brackets in citation with round brackets
+from dataclasses import dataclass, field
+import sphinxcontrib.bibtex.plugin
+
+from sphinxcontrib.bibtex.style.referencing import BracketStyle
+from sphinxcontrib.bibtex.style.referencing.author_year \
+    import AuthorYearReferenceStyle
+
+
+def bracket_style() -> BracketStyle:
+    return BracketStyle(
+        left='(',
+        right=')',
+    )
+
+
+@dataclass
+class RoundBracketReferenceStyle(AuthorYearReferenceStyle):
+    bracket_parenthetical: BracketStyle = field(default_factory=bracket_style)
+    bracket_textual: BracketStyle = field(default_factory=bracket_style)
+    bracket_author: BracketStyle = field(default_factory=bracket_style)
+    bracket_label: BracketStyle = field(default_factory=bracket_style)
+    bracket_year: BracketStyle = field(default_factory=bracket_style)
+
+
+sphinxcontrib.bibtex.plugin.register_plugin(
+    'sphinxcontrib.bibtex.style.referencing',
+    'author_year_round', RoundBracketReferenceStyle)
+
+# Custom style for bibliography labels
+
+from pybtex.style.formatting.unsrt import Style as UnsrtStyle
+from pybtex.style.labels import BaseLabelStyle
+from pybtex.plugin import register_plugin
+
+
+# a simple label style which uses the bibtex keys for labels
+class AuthorYearStyle(BaseLabelStyle):
+
+    def format_labels(self, sorted_entries):
+        for entry in sorted_entries:
+            # create string for label
+            yield entry.persons["author"][0].last_names[0] + ", " +\
+                entry.fields["year"][-4:]
+
+
+class AuthorYear(UnsrtStyle):
+
+    default_label_style = AuthorYearStyle
+
+
+register_plugin('pybtex.style.formatting', 'author_year', AuthorYear)
diff --git a/doc/contribute.rst b/doc/contribute.rst
@@ -340,10 +340,8 @@ Each module in ``doc/reference`` folder ends with the reference section:
     References
     ----------
 
-    .. bibliography:: ../bib/elephant.bib
-       :labelprefix: <module name shortcut>
-       :keyprefix: <module name>-
-       :style: unsrt
+    .. bibliography::
+        :keyprefix: <module name>-
 
 where ``<module name>`` is (by convention) the Python source file name, and
 ``<module name shortcut>`` is what will be displayed to the users.

diff --git a/doc/reference/_spike_train_processing.rst b/doc/reference/_spike_train_processing.rst
@@ -26,17 +26,11 @@ Spike train synchrony
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: cor
-   :keyprefix: correlation-
-   :style: unsrt
-
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: ds
-   :keyprefix: dissimilarity-
-   :style: unsrt
-
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: syn
-   :keyprefix: synchrony-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: correlation-
+
+.. bibliography::
+    :keyprefix: dissimilarity-
+
+.. bibliography::
+    :keyprefix: synchrony-
diff --git a/doc/reference/asset.rst b/doc/reference/asset.rst
@@ -10,7 +10,5 @@ Analysis of Sequences of Synchronous EvenTs (ASSET)
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: asset
-   :keyprefix: asset-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: asset-
diff --git a/doc/reference/causality.rst b/doc/reference/causality.rst
@@ -8,7 +8,5 @@ Causality measures
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: gr
-   :keyprefix: granger-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: granger-
diff --git a/doc/reference/cell_assembly_detection.rst b/doc/reference/cell_assembly_detection.rst
@@ -8,7 +8,5 @@ Cell assembly detection (CAD)
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: cad
-   :keyprefix: cad-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: cad-
diff --git a/doc/reference/change_point_detection.rst b/doc/reference/change_point_detection.rst
@@ -8,7 +8,5 @@ Detection of non-stationary processes
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-    :labelprefix: cpd
+.. bibliography::
     :keyprefix: cpd-
-    :style: unsrt
diff --git a/doc/reference/cubic.rst b/doc/reference/cubic.rst
@@ -8,7 +8,5 @@ Cumulant Based Inference of higher-order Correlation (CuBIC)
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: cubic
-   :keyprefix: cubic-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: cubic-
diff --git a/doc/reference/gpfa.rst b/doc/reference/gpfa.rst
@@ -8,7 +8,5 @@ Gaussian-Process Factor Analysis (GPFA)
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: gpfa
-   :keyprefix: gpfa-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: gpfa-
diff --git a/doc/reference/signal_processing.rst b/doc/reference/signal_processing.rst
@@ -9,7 +9,5 @@ Signal processing
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: sig
-   :keyprefix: signal-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: signal-
diff --git a/doc/reference/spade.rst b/doc/reference/spade.rst
@@ -10,7 +10,5 @@ Spike Pattern Detection and Evaluation (SPADE)
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: spade
-   :keyprefix: spade-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: spade-
diff --git a/doc/reference/spike_train_surrogates.rst b/doc/reference/spike_train_surrogates.rst
@@ -9,7 +9,5 @@ Spike train surrogates
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: sr
-   :keyprefix: surrogates-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: surrogates-
diff --git a/doc/reference/unitary_event_analysis.rst b/doc/reference/unitary_event_analysis.rst
@@ -17,7 +17,5 @@ VR implemented the method, SG and MD provided guidance.
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: ue
-   :keyprefix: unitary_event_analysis-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: unitary_event_analysis-
diff --git a/doc/reference/waveform_features.rst b/doc/reference/waveform_features.rst
@@ -8,7 +8,5 @@ Waveform features
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: wf
-   :keyprefix: waveforms-
-   :style: unsrt
+.. bibliography::
+    :keyprefix: waveforms-
diff --git a/elephant/spike_train_generation.py b/elephant/spike_train_generation.py
@@ -41,11 +41,8 @@
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: gen
+.. bibliography::
    :keyprefix: generation-
-   :style: unsrt
-
 
 :copyright: Copyright 2014-2022 by the Elephant team, see `doc/authors.rst`.
 :license: Modified BSD, see LICENSE.txt for details.

diff --git a/elephant/statistics.py b/elephant/statistics.py
@@ -54,10 +54,8 @@
 References
 ----------
 
-.. bibliography:: ../bib/elephant.bib
-   :labelprefix: st
+.. bibliography::
    :keyprefix: statistics-
-   :style: unsrt
 
 
 :copyright: Copyright 2014-2022 by the Elephant team, see `doc/authors.rst`.

diff --git a/requirements/requirements-docs.txt b/requirements/requirements-docs.txt
@@ -3,7 +3,7 @@ numpydoc>=1.1.0
 jupyter>=1.0.0
 sphinx>=3.3.0
 nbsphinx>=0.8.0
-sphinxcontrib-bibtex==1.0.0
+sphinxcontrib-bibtex>1.0.0
 sphinx-tabs>=1.3.0
 matplotlib>=3.3.2
 # conda install -c conda-forge pandoc