Improve documentation build and visibility of papers/bibtex entries (#…

…213)

* improve landing page

* improve make files

* update titles

* update structure

* rm unused

* update readme

* improve

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix readme

* better

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.gitignore

@@ -74,6 +74,8 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+docc/generated/
+doc/sg_execution_times.rst
 
 # PyBuilder
 target/

README.md

@@ -84,23 +84,43 @@ your question.
 
 # Citing
 
-If you use the ``ICLabel`` model, please consider citing our paper:
-
-    Li et al., (2022). MNE-ICALabel: Automatically annotating ICA components with ICLabel in Python. Journal of Open Source Software, 7(76), 4484, https://doi.org/10.21105/joss.04484
-
-with the corresponding BibTex:
-
-    @article{Li2022,
-        doi       = {10.21105/joss.04484},
-        url       = {https://doi.org/10.21105/joss.04484},
-        year      = {2022},
-        publisher = {The Open Journal},
-        volume    = {7},
-        number    = {76},
-        pages     = {4484},
-        author    = {Adam Li and Jacob Feitelberg and Anand Prakash Saini and Richard Höchenberger and Mathieu Scheltienne},
-        title     = {MNE-ICALabel: Automatically annotating ICA components with ICLabel in Python},
-        journal   = {Journal of Open Source Software}
-    }
+If you use the ``mne-icalabel``, please consider citing our paper:
+
+```
+@article{Li2022,
+  title = {MNE-ICALabel: Automatically annotating ICA components with ICLabel in Python},
+  volume = {7},
+  ISSN = {2475-9066},
+  url = {http://dx.doi.org/10.21105/joss.04484},
+  DOI = {10.21105/joss.04484},
+  number = {76},
+  journal = {Journal of Open Source Software},
+  publisher = {The Open Journal},
+  author = {Li,  Adam and Feitelberg,  Jacob and Saini,  Anand Prakash and H\"{o}chenberger, Richard and Scheltienne,  Mathieu},
+  year = {2022},
+  month = aug,
+  pages = {4484}
+}
+```
+
+And the paper associated to the model used:
+
+- **ICLabel**
+
+```
+@article{PionTonachini2019,
+  title = {ICLabel: An automated electroencephalographic independent component classifier,  dataset,  and website},
+  volume = {198},
+  ISSN = {1053-8119},
+  url = {http://dx.doi.org/10.1016/j.neuroimage.2019.05.026},
+  DOI = {10.1016/j.neuroimage.2019.05.026},
+  journal = {NeuroImage},
+  publisher = {Elsevier BV},
+  author = {Pion-Tonachini,  Luca and Kreutz-Delgado,  Ken and Makeig,  Scott},
+  year = {2019},
+  month = sep,
+  pages = {181–197}
+}
+```
 
 Future versions of the software are aimed at improved models and may have different papers associated with it.

doc/Makefile

@@ -1,20 +1,35 @@
 # Minimal makefile for Sphinx documentation
-#
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -nWT --keep-going
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
+.PHONY: help Makefile clean html html-noplot linkcheck linkcheck-grep view
+
+first_target: help
+
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html             to make standalone HTML files"
+	@echo "  html-noplot      to make standalone HTML files without plotting"
+	@echo "  clean            to clean HTML files"
+	@echo "  linkcheck        to check all external links for integrity"
+	@echo "  linkcheck-grep   to grep the linkcheck result"
+	@echo "  view             to view the built HTML"
+
+html:
+	$(SPHINXBUILD) . _build/html -b html $(SPHINXOPTS)
+
+html-noplot:
+	$(SPHINXBUILD) . _build/html -b html $(SPHINXOPTS) -D plot_gallery=0
+
+clean:
+	rm -rf _build generated sg_execution_times.rst
+
+linkcheck:
+	$(SPHINXBUILD) . _build/linkcheck -b linkcheck -D plot_gallery=0
 
-.PHONY: help Makefile
+linkcheck-grep:
+	@! grep -h "^.*:.*: \[\(\(local\)\|\(broken\)\)\]" _build/linkcheck/output.txt
 
-# 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)
+view:
+	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(PWD)/_build/html/index.html')"