Rewrite references using BibTeX and sphinxcontrib-bibtex

[mwtoews]

I've replaced the documentation's references using sphinxcontrib-bibtex, which is somewhat straightforward to use, and may hopefully allow easier and consistent references to be added to the documentation. Contributors will need to install this onto their Python distribution with:

pip install sphinxcontrib-bibtex

I've set-up the initial references.bib file with JabRef, which is not required, but is a recommended cross-platform GUI to add/edit bibliographic entries in BibTeX format. Also, entries use UTF-8, mostly for international names. This seems to work correctly for both html and pdf outputs.

There were a few corrections/modifications to both the cited text and the entries themselves. I've removed website references, as they just need an inline link. And I've hunted down each citation to fix numbers, DOIs and other details.

At present, sphinxcontrib-bibtex changes the cited text to some other default style, e.g. [Bessel1825] becomes [Bes25] in the output. I think this is customisable, with a bit of work in conf.py. Also, each reference also looks different (is it Vancouver style?). Also probably customisable in conf.py. I can take a look, if anyone thinks this would be good to do. But the main benefit is that the reference style is consistent.

[mwtoews]

One gotcha that I've discovered with sphinxcontrib-bibtex, and could be a bug, is that it will show a WARNING for the alphabetically first citation, i.e.:

$ cd docs
$ make clean
$ make html
docs/source/usage/transformation.rst:110: WARNING: citation not found: Altamimi2002

My workaround is to "update" the reference file, then re-build:

$ touch source/references.rst
$ make html

then everything is fine. I'm not sure if a similar thing would be required in travis/build_docs.sh

[kbevers]

This is awesome, Mike. I like that the references are stored in bibtex format. Good job on collecting the missing info like DOIs.

At present, sphinxcontrib-bibtex changes the cited text to some other default style, e.g. [Bessel1825] becomes [Bes25] in the output. I think this is customisable, with a bit of work in conf.py. Also, each reference also looks different (is it Vancouver style?). Also probably customisable in conf.py. I can take a look, if anyone thinks this would be good to do. But the main benefit is that the reference style is consistent.

It works and it is nice that the references are consistent. I don't particularly like this style for citations since you don't really get a feel for who and what is cited when just reading the text. My preference is Harvard style citations which I also believe is the standard for most texts within the physical sciences. I wonder if it is possible to configure sphinxcontrib-bibtex to use Harvard citations?

[mwtoews]

Yes, I'd prefer Harvard or something more classic too. However, after the looking at the default style for a while, it's not the worst citation style I've encountered.

Unfortunately, It's not as easy as LaTeX is to change the citation style (either in text, or the References section). It is "documented" here and here, but not very cleanly. It may take me a bit of time to unravel the necessary Python smoke for conf.py to make it happen.

[kbevers]

Unfortunately, It's not as easy as LaTeX is to change the citation style (either in text, or the References section). It is "documented" here and here, but not very cleanly. It may take me a bit of time to unravel the necessary Python smoke for conf.py to make it happen.

Yeah, I had a look as well and i reckon it will take a bit of reading in the source code to figure out how to do this. I'll just merge this PR for now and changing the citation style can be changed later.

[mwtoews]

The rest of Pybtex is reasonably documented, and has a simple command-line interface that does the stuff we are interested in modifying, e.g.:

pybtex-format --style alpha references.bib out.html

I've also quickly gone over the Pybtex source code, which looks like an active project in reasonable shape. I'll first see if I can get the key name as the text citation label, as it was before.

[hobu]

Does the docker container that builds the docs need to be updated with bibtex support?

[mwtoews]

Does the docker container that builds the docs need to be updated with bibtex support?

Yes, something like pip install sphinxcontrib-bibtex should install the support. Was it correct to do this in travis/linux_gcc/before_install.sh? Elsewhere? I'm a docker container novice...

[kbevers]

I thinj it's fine like you did it here. It may be slightly faster do add to the docker container but less transparent. Here it is easy to see what is going on and how you set up the system.

[hobu]

Docker container rebuilt and pushed.

[kbevers]

Does that mean we don't have to pip install sphinxcontrib-bibtex on travis?

[hobu]

Yes I hope so.

…

On Jun 22, 2018, at 3:06 PM, Kristian Evers ***@***.***> wrote: Does that mean we don't have to pip install sphinxcontrib-bibtex on travis? — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.