📚 Add sphinxcontrib-bibtex to CONTRIBUTING

Author: shnizzedy

CONTRIBUTING.md

@@ -64,6 +64,56 @@ where `{width}` and `{height}` are the values already present in the existing `w
     <object data="../_static/path/to/chart.svg" type="image/svg+xml"></object>
 ```
 
+## References and citations
+
+[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/) is installed and configured. This extension creates links between the citations and the reference in the reference list and formats citations in referenced BibTeX files using built-in or [custom styles](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references/style.py). To use this Sphinx extension, 
+
+1. Include your citations in a BibTeX file (see the `*.bib` files in [docs/_sources/references](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references) for examples).
+2. Using the key (the text between the opening `{` and the first `,` in a BibTeX entry) use the ReStructuredText syntax `` :cite:`key` `` to cite your reference in a ReStructuredText file.
+3. Include a `.. bibliography::` directive somewhere on any page that you want to use this extension to format references and create two-way links between the references and citations. Specify the (one) BibTeX file for this reference list any formatting for the reference list in this directive. Both `:cite:` and `.. bibliography::` need to be rendered on the same page for the links to generate.
+4. If you will (or might) use more than one `.. bibliography::` directive on a single rendered page (including `.. include::` directives), choose a prefix for the keys and include that prefix in both the `:cite:` role (like `` :cite:`prefix-key` ``) and the bibliography directive (like `:keyprefix: prefix-`).
+5. If you want to include a header over a reference list, use the `.. rubric::` directive above its `.. bibliography` directive.
+6. If the entry type (e.g., `book`, `article`, `misc`) of any of the entries in your BibTeX file(s) is not included in [docs/_sources/references/style.py](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references/style.py), add a `get_{entry_type}_template` [Pybtex](https://pybtex.org) method to `CPAC_DocsStyle`.
+
+For example, if you have a BibTeX file called `cpac_citation.bib` that contains
+
+```BibTeX
+@ARTICLE{cpac2013,
+    AUTHOR={Craddock, Cameron  and  Sikka, Sharad  and  Cheung, Brian  and  Khanuja, Ranjeet  and  Ghosh, Satrajit S
+        and Yan, Chaogan  and  Li, Qingyang  and  Lurie, Daniel  and  Vogelstein, Joshua  and  Burns, Randal  and
+        Colcombe, Stanley  and  Mennes, Maarten  and  Kelly, Clare  and  Di Martino, Adriana  and  Castellanos,
+        Francisco Xavier  and  Milham, Michael},
+    TITLE={Towards Automated Analysis of Connectomes: The {Configurable Pipeline for the Analysis of Connectomes (C-PAC)}},
+    JOURNAL={Frontiers in Neuroinformatics},
+    YEAR={2013},
+    NUMBER={42},
+    URL={http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full},
+    DOI={10.3389/conf.fninf.2013.09.00042},
+    ISSN={1662-5196}
+}
+```
+
+If you include
+
+```rst
+To cite C-PAC, use :cite:`cite-cpac2013`.
+
+.. rubric Cite C-PAC
+
+.. bibliography:: cpac_citation.bib
+   :style: cpac_docs_style
+   :cited:
+   :keyprefix: cite-
+```
+
+The rendered file should look something like
+
+> To cite C-PAC, use <a name="backref1" href="#ref1">[1]</a>.
+> 
+> __Cite C-PAC__
+> 
+> <a name="ref1" href="#backref1">[1]</a> Craddock, C., Sikka, S., Cheung, B., Khanuja, R., Ghosh, S. S., Yan, C., Li, Q., Lurie, D., Vogelstein, J., Burns, R., Colcombe, S., Mennes, M., Kelly, C., Di Martino, A., Castellanos, F. X., and Milham, M. 2013. [Towards automated analysis of connectomes: the Configurable Pipeline for the Analysis of Connectomes (C-PAC).](http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full) *Frontiers in neuroinformatics* 42. doi:[10.3389/conf.fninf.2013.09.00042](https://dx.doi.org/10.3389/conf.fninf.2013.09.00042)
+
 ## Environment notes
 * Because [C-PAC](https://github.com/FCP-INDI/C-PAC.git) and [cpac](https://github.com/FCP-INDI/cpac.git) have conflicting commandline commands, we first run any `cpac` commands in a virtual environment and spoof the `command-output` directive with `code-block` like 
    ```RST

docs/_sources/references/style.py

@@ -16,6 +16,43 @@ def __init__(self, *args, **kwargs):
             sorting_style=NoSort
         )
 
+    def format_doi(self, doi):
+        return join(sep=':')[
+            words['doi'],
+            href[join(sep='/')[
+                'https://dx.doi.org', doi
+            ], doi]
+        ]
+
+    def get_article_template(self, entry):
+        template = toplevel[optional[
+            sentence[self.format_names('author')]],
+            optional[sentence[date]],
+            optional[
+                href[
+                    field('url'),
+                    self.format_title(entry, 'title')
+                ] if entry.fields.get('url') else
+                self.format_title(entry, 'title')
+            ],
+            sentence[join(sep=' ')[
+                optional[tag('em')[join(sep=', ')[
+                    self.format_title(entry, 'journal', as_sentence=False),
+                    optional_field('volume')
+                ]]],
+                optional[join(sep='')[
+                    ':' if entry.fields.get('volume') else '',
+                    optional_field("number")
+                ] if entry.fields.get('number') else ''],
+            ]],
+            optional[join(sep='')[
+                ', pp. ', optional_field('pages')
+            ] if entry.fields.get('pages') else ''],
+            optional[self.format_doi(optional_field('doi'))],
+            sentence[optional_field('note')],
+        ]
+        return template
+
     def get_book_template(self, entry):
         template = toplevel[optional[
             sentence[self.format_names('author')]],