[WIP][DOC] introducing sphinxcontrib-Bibtex to improve reference management

[skoudoro]

build succeeded, 1871 warnings.

A lot of those warning are due to references. This PR add sphinxcontrib-bibtex to manage references, avoid duplication, avoid formatting error, etc.

This PR will take a bit of time to be finalize so I wonder if I should split it in multiple PR or not. It should make review process easier. Looking forward for your feedback.

[codecov]

Codecov Report

Merging #2810 (381f4fe) into master (89e4ab6) will increase coverage by 0.01%.
The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2810      +/-   ##
==========================================
+ Coverage   81.45%   81.47%   +0.01%     
==========================================
  Files         144      144              
  Lines       20054    20054              
  Branches     3192     3192              
==========================================
+ Hits        16335    16339       +4     
+ Misses       2909     2906       -3     
+ Partials      810      809       -1     

Impacted Files	Coverage Δ
dipy/reconst/dki.py	94.49% <ø> (ø)

... and 1 file with indirect coverage changes

[arokem]

Splitting it up makes sense to me. There's no reason to wait until it's all done to merge these additions, right?

[skoudoro]

There's no reason to wait until it's all done to merge these additions, right?

right, so you can merge, and I will do that step by step starting with the examples and then the docstring in the codebase

[arokem]

Looks great! What do you think about normalizing the bibtex keys?

[arokem]

This is a bit of an eyesore. Maybe we could we use a uniform format for bibtex keys? For example, "NetoHenriques2015NeuroImage"

[skoudoro]

This is a bit of an eyesore

ahahah, you are right

Maybe we could we use a uniform format for bibtex keys?

I agree, even if the bibtex file is big. I like the beginning of your example but I do not think we should finish with the journal. so just {firstname}{name}{year}{letter | optional if multiple paper} is that ok ?

[arokem]

Yeah. That would work well.

[jhlegarreta]

Thanks for doing this @skoudoro.

Not sure if sphinxcontrib-bibtex is actively maintained, but I do agree that this or other similar mechanism is required.

Some comments in-line.

[jhlegarreta]

This symbol and other similar ones introduced are not plain, BIbTeX symbols; e.g. the correct BibTeX spelling for Evren's surname would be \"{O}zarslan. I can have a go to the file to fix them. I assume the changes were done inadvertently introduced when running some tool.

[jhlegarreta]

I can have a look at this and amend the commit.

[jhlegarreta]

Similar to the above, but in this case the hyphen does exist in BibTeX; usually BibTeX is smart enough to change it to the en dash for page ranges.

[jhlegarreta]

I agree to the conversation in #2810 (comment). I am sure there is also a way to generate the keys automatically using a self-defined pattern, but we may leave that as a separate task/PR.

Also, making all entries consistent (fields, names, etc.) would ease reading the file (e.g. when maintainers need to go through it). Something that might be partially automated? Probably best as a separate PR.

[jhlegarreta]

Also, If BibTeX references will be/are split across modules (e.g. segment, tracking, docs, etc.), it may be harder to maintain, as the same reference may fall into different categories, duplicated entries may exist (unless the automated tool prevents them, but then it may not be evident where a reference should belong to).