draft pr for readthedocs

.gitignore

@@ -71,6 +71,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/modules/_autosummary
 
 # PyBuilder
 target/

.readthedocs.yml

@@ -1,9 +1,14 @@
 version: 2
 
 build:
-  os: "ubuntu-22.04"
-  tools:
-   python: "3.8"
+   os: "ubuntu-22.04"
+   tools:
+      python: "3.8"
+   jobs:
+      pre_build:
+      - cat brainscore_language/utils/document_plugins.py
+      - python brainscore_language/utils/document_plugins.py
+
 
 python:
    install:

brainscore_language/utils/document_plugins.py

@@ -0,0 +1,24 @@
+""" Make plugin details available to readthedocs """
+
+from pathlib import Path
+from brainscore_core.plugin_management.plugin_utils import get_all_plugin_info
+from brainscore_core.plugin_management.document_plugins import create_bibfile, update_readthedocs
+
+
+BIBS_DIR = Path(Path(__file__).parents[2], 'docs', 'source', 'bibtex')
+PLUGINS_DOC = Path(Path(__file__).parents[2], 'docs', 'source', 'modules')
+GITHUB_DIR = 'https://github.com/brain-score/language/tree/main/brainscore_language/'
+
+
+def update_docs():
+    all_plugin_info = get_all_plugin_info(Path(__file__).parents[1])
+    print('running document_plugins.py')
+    print(f"all_plugin_info: {all_plugin_info}")
+    for plugin_type in all_plugin_info:
+        create_bibfile(all_plugin_info[plugin_type], BIBS_DIR, plugin_type) # plugin type .bib file
+    create_bibfile(all_plugin_info, BIBS_DIR) # one .bib file to rule them all
+    update_readthedocs(all_plugin_info, PLUGINS_DOC, GITHUB_DIR)
+
+
+if __name__ == '__main__':
+    update_docs()

docs/Makefile

@@ -1,20 +1,14 @@
 # Minimal makefile for Sphinx documentation
-#
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -2,4 +2,6 @@
 
 Sphinx>=4
 sphinx_rtd_theme
-recommonmark
+recommonmark
+sphinxcontrib-bibtex
+rstcloth

docs/source/bibtex/data.bib

@@ -0,0 +1,40 @@
+@article{blank2014functional,
+  title={A functional dissociation between language and multiple-demand systems revealed in patterns of BOLD signal fluctuations},
+  author={Blank, Idan and Kanwisher, Nancy and Fedorenko, Evelina},
+  journal={Journal of neurophysiology},
+  volume={112},
+  number={5},
+  pages={1105--1118},
+  year={2014},
+  publisher={American Physiological Society Bethesda, MD}
+}
+@article{fedorenko2016neural,
+  title={Neural correlate of the construction of sentence meaning},
+  author={Fedorenko, Evelina and Scott, Terri L and Brunner, Peter and Coon, William G and Pritchett, Brianna and 
+          Schalk, Gerwin and Kanwisher, Nancy},
+  journal={Proceedings of the National Academy of Sciences},
+  volume={113},
+  number={41},
+  pages={E6256--E6262},
+  year={2016},
+  publisher={National Acad Sciences}
+}
+@proceedings{futrell2018natural,
+  title={The Natural Stories Corpus},
+  author={Futrell, Richard and Gibson, Edward and Tily, Harry J. and Blank, Idan and Vishnevetsky, Anastasia and
+          Piantadosi, Steven T. and Fedorenko, Evelina},
+  conference={International Conference on Language Resources and Evaluation (LREC)},
+  url={http://www.lrec-conf.org/proceedings/lrec2018/pdf/337.pdf},
+  year={2018}
+}
+@article{pereira2018toward,
+  title={Toward a universal decoder of linguistic meaning from brain activation},
+  author={Pereira, Francisco and Lou, Bin and Pritchett, Brianna and Ritter, Samuel and Gershman, Samuel J 
+          and Kanwisher, Nancy and Botvinick, Matthew and Fedorenko, Evelina},
+  journal={Nature communications},
+  volume={9},
+  number={1},
+  pages={1--13},
+  year={2018},
+  publisher={Nature Publishing Group}
+}

docs/source/bibtex/refs.bib

@@ -0,0 +1,40 @@
+@article{blank2014functional,
+  title={A functional dissociation between language and multiple-demand systems revealed in patterns of BOLD signal fluctuations},
+  author={Blank, Idan and Kanwisher, Nancy and Fedorenko, Evelina},
+  journal={Journal of neurophysiology},
+  volume={112},
+  number={5},
+  pages={1105--1118},
+  year={2014},
+  publisher={American Physiological Society Bethesda, MD}
+}
+@article{fedorenko2016neural,
+  title={Neural correlate of the construction of sentence meaning},
+  author={Fedorenko, Evelina and Scott, Terri L and Brunner, Peter and Coon, William G and Pritchett, Brianna and 
+          Schalk, Gerwin and Kanwisher, Nancy},
+  journal={Proceedings of the National Academy of Sciences},
+  volume={113},
+  number={41},
+  pages={E6256--E6262},
+  year={2016},
+  publisher={National Acad Sciences}
+}
+@proceedings{futrell2018natural,
+  title={The Natural Stories Corpus},
+  author={Futrell, Richard and Gibson, Edward and Tily, Harry J. and Blank, Idan and Vishnevetsky, Anastasia and
+          Piantadosi, Steven T. and Fedorenko, Evelina},
+  conference={International Conference on Language Resources and Evaluation (LREC)},
+  url={http://www.lrec-conf.org/proceedings/lrec2018/pdf/337.pdf},
+  year={2018}
+}
+@article{pereira2018toward,
+  title={Toward a universal decoder of linguistic meaning from brain activation},
+  author={Pereira, Francisco and Lou, Bin and Pritchett, Brianna and Ritter, Samuel and Gershman, Samuel J 
+          and Kanwisher, Nancy and Botvinick, Matthew and Fedorenko, Evelina},
+  journal={Nature communications},
+  volume={9},
+  number={1},
+  pages={1--13},
+  year={2018},
+  publisher={Nature Publishing Group}
+}

docs/source/conf.py

@@ -35,6 +35,8 @@
     'recommonmark',
     'sphinx.ext.viewcode',
     'sphinx_rtd_theme',
+    'sphinxcontrib.bibtex',
+    'sphinx.ext.autosectionlabel'
 ]
 autosummary_generate = True  # Turn on sphinx.ext.autosummary
 
@@ -53,6 +55,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# allows BibTeX citations to be inserted into docs
+bibtex_bibfiles = ['bibtex/refs.bib']
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -61,11 +66,6 @@
 #
 html_theme = "sphinx_rtd_theme"
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
 
 def skip(app, what, name, obj, would_skip, options):
     if name in ("__init__", "__call__"):

docs/source/index.rst

@@ -25,4 +25,5 @@ The `score` function is the primary entry point to score a model on a benchmark.
    modules/benchmark_tutorial
    examples
    modules/api_reference
+   modules/plugins
    Glossary <https://brain-score-core.readthedocs.io/en/latest/modules/glossary.html>

docs/source/modules/benchmark_tutorial.rst

@@ -208,7 +208,7 @@ For example:
 
         def __call__(self, candidate: ArtificialSubject) -> Score:
             candidate.start_behavioral_task(ArtificialSubject.Task.reading_times)  # or any other task
-            # or e.g. candidate.start_start_recording(recording_target=ArtificialSubject.RecordingTarget.language_system,
+            # or e.g. candidate.start_neural_recording(recording_target=ArtificialSubject.RecordingTarget.language_system,
             #                                            recording_type=ArtificialSubject.RecordingType.fMRI)
             predictions = candidate.digest_text(stimuli)['behavior']
             raw_score = self.metric(predictions, self.data)