MRG: proof of concept for sphinxcontrib-bibtex (mne-tools#6931)

* WIP: proof of concept for sphinxcontrib-bibtex

* test upstream fix on circle

* adapt to upstream changes

* fix title capitalization

* fix flake

* fix bibtex acronym capitalization

* fix pydocstyle

* fix a couple dates in bib file

* test file includes

* use style unsrt

* add new ref; fix duplicated surname [skip travis]

* add general bibliography

* fixes for a couple refs

* add refs in forward.rst

* bib file cleanup

* add comments to Matti's bibliography page

these will be converted to proper :footcite: references when the pending
change to sphinxcontrib-bibtex hits (it will allow multiple footbibliography::
directives in a single .rst file)

* add general bib to TOC; swich list style of general bib; add ordering note

* ignore "not cited" warnings generated by general bibliography

* more bibtex cleanup

* prefer "all" over "notcited" for general bib

* make compatible with latest sphinxcontrib-bitex changes

* test Matti's annotated bibliography

* no longer need to suppress warnings

* tired of waiting for release; pin to commit

* fix rebase error

* fix footbib

* fix another rebase error

doc/_includes/channel_interpolation.rst

@@ -13,7 +13,7 @@ Spherical spline interpolation (EEG)
    can omit the title from the include:
    channel-interpolation-begin-content
 
-In short, data repair using spherical spline interpolation [1]_ consists of the following steps:
+In short, data repair using spherical spline interpolation :footcite:`PerrinEtAl1989` consists of the following steps:
 
 * Project the good and bad electrodes onto a unit sphere
 * Compute a mapping matrix that maps :math:`N` good channels to :math:`M` bad channels
@@ -74,6 +74,4 @@ and the bad channel will be fixed.
 References
 ~~~~~~~~~~
 
-.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989).
-       Spherical splines for scalp potential and current density mapping.
-       *Electroencephalography Clinical Neurophysiology* 72(2), 184-187.
+.. footbibliography::

doc/_includes/forward.rst

@@ -657,7 +657,7 @@ are rather far away from the brain sources, :func:`mne.make_forward_solution`
 takes them into account in the computations. If the data file has software
 gradient compensation activated, it computes the field of at the reference
 sensors in addition to the main MEG sensor array and computes a compensated
-forward solution`.
+forward solution.
 
 The EEG sphere model definition file
 ------------------------------------
@@ -697,8 +697,9 @@ EEG forward solution in the sphere model
    :ref:`plot_source_alignment_without_mri`.
 
 When the sphere model is employed, the computation of the EEG solution can be
-substantially accelerated by using approximation methods described by Mosher,
-Zhang, and Berg, see :ref:`CEGEGDEI` (Mosher *et al.* and references therein).
+substantially accelerated by using approximation methods described by Mosher
+:footcite:`MosherEtAl1999`, Zhang :footcite:`Zhang1995`, and Berg
+:footcite:`BergScherg1994`.
 :func:`mne.make_forward_solution` approximates the solution with three dipoles
 in a homogeneous sphere whose locations and amplitudes are determined by
 minimizing the cost function:
@@ -723,3 +724,10 @@ this purpose, :func:`mne.average_forward_solutions` computes a weighted average
 of several forward solutions. The function averages both MEG and EEG forward
 solutions. Usually the EEG forward solution is identical across runs because
 the electrode locations do not change.
+
+.. target for :end-before: forward-end-content
+
+References
+~~~~~~~~~~
+
+.. footbibliography::

doc/_includes/inverse.rst

@@ -233,9 +233,9 @@ independent of  :math:`L` and, for fixed :math:`\lambda`, we see directly that
 Noise normalization
 -------------------
 
-The noise-normalized linear estimates introduced by Dale et al. [2]_ require
-division of the expected current amplitude by its variance. Noise normalization
-serves three purposes:
+The noise-normalized linear estimates introduced by Dale et al.
+:footcite:`DaleEtAl1999` require division of the expected current amplitude by
+its variance. Noise normalization serves three purposes:
 
 - It converts the expected current value into a dimensionless statistical test
   variable. Thus the resulting time and location dependent values are often
@@ -446,6 +446,4 @@ Generalizing, for any combination of sums and differences, where :math:`w_i =
 References
 ~~~~~~~~~~
 
-.. [2] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis.
-       I. Segmentation and surface reconstruction." *Neuroimage* 9, 179-94.
-       doi: 10.1006/nimg.1998.0395
+.. footbibliography::

doc/_static/style.css

@@ -441,7 +441,9 @@ div.institutions a {
   .institution_lg {
     max-height: 60px;
   }
-
+  .hidden {
+    display: none;
+  }
   /* Pandas DataFrame _repr_html_ */
 table.dataframe th,td {
     padding: 5px;

doc/bibliography.rst

@@ -0,0 +1,8 @@
+General bibliography
+====================
+
+The references below are arranged alphabetically by first author.
+
+.. bibliography:: ./references.bib
+   :all:
+   :list: enumerated

doc/conf.py

@@ -46,7 +46,7 @@
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.5'
+needs_sphinx = '2.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -67,6 +67,8 @@
     'gen_commands',
     'sphinx_bootstrap_theme',
     'sphinx_bootstrap_divs',
+    'sphinxcontrib.bibtex',
+    'sphinxcontrib.bibtex2',
 ]
 
 linkcheck_ignore = [
@@ -328,6 +330,14 @@
     'picard': ('https://pierreablin.github.io/picard/', None),
 }
 
+
+##############################################################################
+# sphinxcontrib-bibtex
+
+bibtex_bibfiles = ['./references.bib']
+bibtex_style = 'unsrt'
+bibtex_footbibliography_header = ''
+
 ##############################################################################
 # sphinx-gallery
 

doc/overview/datasets_index.rst

@@ -152,9 +152,11 @@ EEGBCI motor imagery
 ====================
 :func:`mne.datasets.eegbci.load_data`
 
-The EEGBCI dataset is documented in [2]_. The data set is available at PhysioNet [3]_.
-The dataset contains 64-channel EEG recordings from 109 subjects and 14 runs on each subject in EDF+ format.
-The recordings were made using the BCI2000 system. To load a subject, do::
+The EEGBCI dataset is documented in :footcite:`SchalkEtAl2004`. The data set is
+available at PhysioNet :footcite:`GoldbergerEtAl2000`. The dataset contains
+64-channel EEG recordings from 109 subjects and 14 runs on each subject in EDF+
+format. The recordings were made using the BCI2000 system. To load a subject,
+do::
 
     from mne.io import concatenate_raws, read_raw_edf
     from mne.datasets import eegbci
@@ -232,13 +234,13 @@ Visual 92 object categories
 This dataset is recorded using a 306-channel Neuromag vectorview system.
 
 Experiment consisted in the visual presentation of 92 images of human, animal
-and inanimate objects either natural or artificial [4]_. Given the high number
-of conditions this dataset is well adapted to an approach based on
-Representational Similarity Analysis (RSA).
+and inanimate objects either natural or artificial :footcite:`CichyEtAl2014`.
+Given the high number of conditions this dataset is well adapted to an approach
+based on Representational Similarity Analysis (RSA).
 
 .. topic:: Examples
 
-    * :ref:`Representational Similarity Analysis (RSA) <ex-rsa-noplot>`: Partially replicates the results from Cichy et al. (2014).
+    * :ref:`Representational Similarity Analysis (RSA) <ex-rsa-noplot>`: Partially replicates the results from :footcite:`CichyEtAl2014`.
 
 
 mTRF Dataset
@@ -251,11 +253,12 @@ which is also available `here <https://sourceforge.net/projects/aespa/files/>`_.
 The experiment consisted of subjects listening to natural speech.
 The dataset contains several feature representations of the speech stimulus,
 suitable for using to fit continuous regression models of neural activity.
-More details and a description of the package can be found in [5]_.
+More details and a description of the package can be found in
+:footcite:`CrosseEtAl2016`.
 
 .. topic:: Examples
 
-    * :ref:`Receptive Field Estimation and Prediction <ex-receptive-field-mtrf>`: Partially replicates the results from Crosse et al. (2016).
+    * :ref:`Receptive Field Estimation and Prediction <ex-receptive-field-mtrf>`: Partially replicates the results from :footcite:`CrosseEtAl2016`.
 
 
 .. _kiloword-dataset:
@@ -264,17 +267,18 @@ Kiloword dataset
 ================
 :func:`mne.datasets.kiloword.data_path`.
 
-This dataset consists of averaged EEG data from 75 subjects performing a lexical decision
-task on 960 English words [6]_. The words are richly annotated, and can be used for e.g.
-multiple regression estimation of EEG correlates of printed word processing.
+This dataset consists of averaged EEG data from 75 subjects performing a
+lexical decision task on 960 English words :footcite:`DufauEtAl2015`. The words
+are richly annotated, and can be used for e.g. multiple regression estimation
+of EEG correlates of printed word processing.
 
 
 4D Neuroimaging / BTi dataset
 =============================
 :func:`mne.datasets.phantom_4dbti.data_path`.
 
-This dataset was obtained with a phantom on a 4D Neuroimaging / BTi system at the MEG
-center in La Timone hospital in Marseille.
+This dataset was obtained with a phantom on a 4D Neuroimaging / BTi system at
+the MEG center in La Timone hospital in Marseille.
 
 .. topic:: Examples
 
@@ -323,7 +327,7 @@ recordings, containing EEG, EOG, chin EMG, and event markers. Some records also
 contain respiration and body temperature. Corresponding hypnograms (sleep
 patterns) were manually scored by well-trained technicians according to the
 Rechtschaffen and Kales manual, and are also available. If you use these
-data please cite [7]_ and [8]_.
+data please cite :footcite:`KempEtAl2000` and :footcite:`GoldbergerEtAl2000`.
 
 .. topic:: Examples
 
@@ -370,7 +374,8 @@ LIMO Dataset
 ^^^^^^^^^^^^
 :func:`mne.datasets.limo.load_data`.
 
-In the original LIMO experiment (see [9]_), participants performed a
+In the original LIMO experiment (see :footcite:`RousseletEtAl2010`), participants
+performed a
 two-alternative forced choice task, discriminating between two face stimuli.
 Subjects discriminated the same two faces during the whole experiment.
 The critical manipulation consisted of the level of noise added to the
@@ -393,21 +398,10 @@ discriminate.
 References
 ==========
 
-.. [2] Schalk, G., McFarland, D.J., Hinterberger, T., Birbaumer, N., Wolpaw, J.R. (2004) BCI2000: A General-Purpose Brain-Computer Interface (BCI) System. IEEE TBME 51(6):1034-1043
+.. footbibliography::
 
-.. [3] Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. (2000) PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals. Circulation 101(23):e215-e220
 
-.. [4] Cichy, R. M., Pantazis, D., & Oliva, A. Resolving human object recognition in space and time. Nature Neuroscience (2014): 17(3), 455-462
-
-.. [5] Crosse, M. J., Di Liberto, G. M., Bednar, A., & Lalor, E. C. The Multivariate Temporal Response Function (mTRF) Toolbox: A MATLAB Toolbox for Relating Neural Signals to Continuous Stimuli. Frontiers in Human Neuroscience (2016): 10.
-
-.. [6] Dufau, S., Grainger, J., Midgley, KJ., Holcomb, PJ. A thousand words are worth a picture: Snapshots of printed-word processing in an event-related potential megastudy. Psychological science, 2015
-
-.. [7] B Kemp, AH Zwinderman, B Tuk, HAC Kamphuisen, JJL Oberyé. Analysis of a sleep-dependent neuronal feedback loop: the slow-wave microcontinuity of the EEG. IEEE-BME 47(9):1185-1194 (2000). https://ieeexplore.ieee.org/document/867928
-
-.. [8] Goldberger AL, Amaral LAN, Glass L, Hausdorff JM, Ivanov PCh, Mark RG, Mietus JE, Moody GB, Peng C-K, Stanley HE. PhysioBank, PhysioToolkit, and PhysioNet: Components of a New Research Resource for Complex Physiologic Signals. Circulation 101(23):e215-e220 [Circulation Electronic Pages; http://circ.ahajournals.org/cgi/content/full/101/23/e215]; 2000 (June 13).
-
-.. [9] Rousselet, G. A., Gaspar, C. M., Pernet, C. R., Husk, J. S., Bennett, P. J., & Sekuler, A. B. (2010). Healthy aging delays scalp EEG sensitivity to noise in a face discrimination task. Frontiers in psychology, 1, 19. https://doi.org/10.3389/fpsyg.2010.00019
+.. LINKS
 
 .. _auditory dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetAuditory
 .. _resting state dataset tutorial: https://neuroimage.usc.edu/brainstorm/DatasetResting

doc/overview/faq.rst

@@ -300,9 +300,9 @@ available. It is thus suggested to regularize the noise covariance
 matrix (see :ref:`cov_regularization_math`), especially if only few samples
 are available. Unfortunately it is not easy to tell the effective number of
 samples, hence, to choose the appropriate regularization. In MNE-Python,
-regularization is done using advanced regularization methods described in [1]_.
-For this the 'auto' option can be used. With this option cross-validation will
-be used to learn the optimal regularization::
+regularization is done using advanced regularization methods described in
+:footcite:`EngemannGramfort2015`. For this the 'auto' option can be used. With
+this option cross-validation will be used to learn the optimal regularization::
 
     >>> import mne
     >>> epochs = mne.read_epochs(epochs_path) # doctest: +SKIP
@@ -329,11 +329,11 @@ by which the squared sum across sensors is divided when computing the whitened
 :term:`GFP`. The whitened :term:`GFP` also helps detecting spurious late evoked
 components which can be the consequence of over- or under-regularization.
 
-Note that if data have been processed using signal space separation (SSS) [2]_,
-gradiometers and magnetometers will be displayed jointly because both are
-reconstructed from the same SSS basis vectors with the same numerical rank.
-This also implies that both sensor types are not any longer linearly
-independent.
+Note that if data have been processed using signal space separation (SSS)
+:footcite:`TauluEtAl2005`, gradiometers and magnetometers will be displayed
+jointly because both are reconstructed from the same SSS basis vectors with the
+same numerical rank. This also implies that both sensor types are not any
+longer linearly independent.
 
 These methods for evaluation can be used to assess model violations. Additional
 introductory materials can be found `here
@@ -349,15 +349,11 @@ compared::
 This will plot the whitened evoked for the optimal estimator and display the
 :term:`GFPs <GFP>` for all estimators as separate lines in the related panel.
 
+
 References
 ----------
 
-.. [1] Engemann D. and Gramfort A. (2015) Automated model selection in
-       covariance estimation and spatial whitening of MEG and EEG signals,
-       vol. 108, 328-342, NeuroImage.
-
-.. [2] Taulu, S., Simola, J., Kajola, M., 2005. Applications of the signal
-       space separation method. IEEE Trans. Signal Proc. 53, 3359–3372.
+.. footbibliography::
 
 .. LINKS
 

doc/overview/implementation.rst

@@ -108,7 +108,7 @@ The forward solution
 
 .. include:: ../_includes/forward.rst
    :start-after: forward-begin-content
-
+   :end-before: forward-end-content
 
 .. _ch_mne:
 
@@ -131,12 +131,4 @@ Morphing and averaging source estimates
 
 References
 ^^^^^^^^^^
-
-.. [1] Perrin, F., Pernier, J., Bertrand, O. and Echallier, JF. (1989).
-       Spherical splines for scalp potential and current density mapping.
-       *Electroencephalography Clinical Neurophysiology* 72(2), 184-187.
-       doi: 10.1016/0013-4694(89)90180-6
-
-.. [2] Dale AM, Fischl B, Sereno MI (1999). "Cortical surface-based analysis.
-       I. Segmentation and surface reconstruction." *Neuroimage* 9, 179-94.
-       doi: 10.1006/nimg.1998.0395
+.. footbibliography::

doc/overview/index.rst

@@ -53,6 +53,7 @@ categories above) are linked here:
     migrating
     cite
     get_help
+    ../bibliography
 
 Documentation for the related C and MATLAB tools are available here: