Author, year citations

[amichuda]

Currently, jupyter-book uses sphinxcontrib-bibtex for creating citation keys in text using the cite directive.

However, for academic citations (at least for my field) the convention is to use an author, year citation key.

There's an issue open about this on sphinxcontrib-bibtex: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/201

I think it comes down to just creating a custom citation class using pybtex.

I think this is something in my wheelhouse to do a PR for if it's something you all think has value.

Would this be a matter of just adding it to some jupyter-book conf.py? And then registering it somehow?

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[choldgraf]

I am not sure exactly how to do this, but it would be great to see it done! If you can figure out how to get sphinxcontrib-bibtex to display more custom outputs, then we can write up some docs as a pattern for users that wish to control this. (perhaps we could also upstream some improvements for certain documentation styles to sphinxcontrib-bibtex?)

[stefanuddenberg]

Seconded; it would be nice to have APA style citations in particular for my own work.

[jstac]

+1, we use author (year) in economics. Thanks @amichuda, would be very happy to have this.

[choldgraf]

Y'all should +1 (👍) the top comment in this issue so that it shows up on the issue tracker ;-)

[stefanuddenberg]

I was able to integrate the code for this package into pybtex, but there are still two issues I need to resolve: (1) removing the square brackets from the in-line citation, and (2) removing the citation 'name' from the entry in the bibliography. Pictures of odd formatting below.

[amichuda]

I was able to integrate the code for this package into pybtex, but there are still two issues I need to resolve: (1) removing the square brackets from the in-line citation, and (2) removing the citation 'name' from the entry in the bibliography. Pictures of odd formatting below.

That's great! I've been playing around with inheriting from the alpha class and I've run into the same issue. Is there a way I can take a look at the code?

My main question, though, right now is where to throw in the code... From reading the code, I take it that it has to be integrated somehow into default_config.yml? Or is there something in commands/ that can append the lines into the final config?

Sorry for the dumb question. Based on the issue above, you're just supposed to include the overriden classes into conf.py, so what would be the best way to do that?

[stefanuddenberg]

@amichuda There is an associated PyPI package for that repo I linked earlier. You can try installing that, but it didn't work for me when I tried it some months ago. Instead, I took all of the relevant files from that repo and put them into the corresponding folders in the pybtex folder for my conda environment. So formatting/apa.py went into pybtex/formatting/apa.py, and so on. I think that's all I had to do, and then it knows about the apa style when I call for the book to be built. Still having trouble figuring out the bracket and extra citation key issue though...

[stefanuddenberg]

pip install pybtex-apa-style works for me now. My bracket issue remains, however...

[amichuda]

My bracket issue remains, however...

Checking the source of sphinxcontrib-bibtex, I think it's hard-coded. See issue I opened up here. Assuming I read the code right, it doesn't seem like something that pybtex could overcome right?

https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/203

[stefanuddenberg]

I stumbled across the same piece of code as well; I think you are right. Not sure whether there's an alternative to making a separate fork of sphinxcontrib-bibtex at this point.

[choldgraf]

Perhaps we could make some upstream contributions to sphinxcontrib-bibtex?

[stefanuddenberg]

Would be happy to help with that; putting my wish-list for publication-ready articles on here for posterity's sake, as I imagine they're all related to sphinxcontrib-bibtex's particular implementation (I understand that these would require separate issues to be raised):

• bracketless references (this will allow multiple citations to be present in the same line for free)
• bibliography without redundant in-line citation key before each reference
• custom title for bibliography (e.g., "References")
• parenthetical citations (e.g., "AuthorName (YYYY) found that...")
• custom line spacing of the document (e.g., single spacing, double spacing)
• custom page alignment for headings (e.g., left, center, right)

[choldgraf]

Nice - thanks for that wishlist, do you think you could make a new issue out of it? I think it's valuable to track general lists of improvements we want to see to citations support.

In general my approach is that we should upstream everything as much as possible. If we hit an impasse with sphinxcontrib-bibtex then we can discuss creating a new implementation as a last resort

[jobovy]

In case it helps, author-year citations of various forms are supported in a very hacky way by my sphinx-astrorefs Sphinx extension:

https://github.com/jobovy/sphinx-astrorefs

It's really way too hacky to incorporate here or in sphinxcontrib.bibtex, but the pybtex author-year and sorting style that's defined might be useful longer term.

[amichuda]

In case it helps, author-year citations of various forms are supported in a very hacky way by my sphinx-astrorefs Sphinx extension:

Uhhhh that actually seems kind of perfect...

How did you get rid of square brackets when dealing with inline citations?

It's really way too hacky to incorporate here or in sphinxcontrib.bibtex, but the pybtex author-year and sorting style that's defined might be useful longer term.

Can you explain what's hacky about it. From a cursory glance at the description, it seems like a custom style using pybtex no?

The author of sphinxcontrib.bibtex is starting to do the work of incorporating changes that would sort of get it where your extension already is.

https://github.com/mcmtroffaes/sphinxcontrib-bibtex/pull/213

[jobovy]

It's hacky, because it takes the HTML and LaTeX outputs and processes them to replace the square brackets with parentheses or nothing. It seems to work for now, but such a hack is probably not very long time stable wrt changes to the way Sphinx generates the HTML/LaTeX and it may also not work for all Sphinx themes. I think the proper way would be to create new Sphinx roles for :citep:, :citet: and :citealt roles, but that's currently beyond my pay grade 😄

I saw the mcmtroffaes/sphinxcontrib-bibtex#213 PR, but that doesn't allow for the full set of different citation commands that I need.

[amichuda]

I saw the mcmtroffaes/sphinxcontrib-bibtex#213 PR, but that doesn't allow for the full set of different citation commands that I need.

Agreed, but that PR would be able to help at least with the issue of processing the files again, correct?

I like your idea of defining new roles, I wonder how difficult that would be to implement? Would that require PRs in Sphinx, itself?

[jobovy]

I saw the mcmtroffaes/sphinxcontrib-bibtex#213 PR, but that doesn't allow for the full set of different citation commands that I need.

Agreed, but that PR would be able to help at least with the issue of processing the files again, correct?

I like your idea of defining new roles, I wonder how difficult that would be to implement? Would that require PRs in Sphinx, itself?

I'm not sure. I think you can define new roles outside of Sphinx, but the :cite: role has a bit of a special place in how it's handled in some cases. For example, I develop many of my Sphinx as jupyter notebooks and then the way you cite in notebooks (with <cite data-cite=...) has to be converted to RST using a notebook converter. So you'd probably have to edit the notebook converter itself (I'm not sure how new roles are translated...).

[amichuda]

Some really cool news from sphinxcontrib-bibtex:

https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/203

[choldgraf]

amazing!

[joh]

I would also love to have this option available in jupyter-book. As far as I can understand, custom formatting is now supported by sphinxcontrib-bibtex. However, according to the documentation, custom formatting involves adding some custom python code to conf.py. Is there a way to do this in jupyter-book?

[jbusecke]

Hi everyone, I am trying to homogenize the citation/bibliography style for this project(https://github.com/OceanGlidersCommunity/Oxygen_SOP/issues/88). Ideally we would like the Bibliography to show the same format as the citations (example here).

Example of text citation:

Correponding Bibliography entry:

I guess what I am most unclear about is how I could implement this custom sphinxcontrib-bibtex code in the _config.yml syntax if that is even possible.

If this is not possible, could we export and modify the conf.py file and then use that in the book build? Sorry if these are pretty basic questions, I only have a little experience with jupyter book so far.

If someone here has some concrete tips on how to implement this, I would very much appreciate it. I think this is broadly relevant for many folks in e.g. the earth science community. If there is a solution, I'd be happy to work on adding that to the docs if needed.

Thanks!

[observingClouds]

Hi everyone,

while searching for a possibility to get the typical academic citation style (author, year) in a Jupyter book I found this issue. You have done so much great work here and it helped me to come up with a solution ( at least for what I wanted ):

• citations with round brackets ( author et al. ( year) and ( author et al. , year ) )
• citation keys of the format author et al. ( year) in the bibliography

For this Jupyter book this has been achieved with this PR.

I want to mention that I'm also very new to this environment and did not know how to bring all the mentioned resources together in the _config.yml as @jbusecke mentioned as well.

I decided to create an extension folder _ext, where I included both the plugin for round brackets and for custom reference styles. The latter I adapted to make use of the pydtex-apa-style package.

These extensions can then be loaded within _config.yml:

sphinx:
   local_extensions:
     apastyle: _ext/
     bracket_citation_style: _ext/

and referenced:

bibtex_reference_style    : author_year_round
bibtex_default_style        : myapastyle

It's important that the files in the extension folder have a setup function because this is called when loading the extension.

As a result I end up with:

and or depending on the usage of cite:t or cite:p

For all the details please check out the PR

I hope this is useful!

[jbusecke]

Thank you so much for outlining these steps @observingClouds! I will try to implement this soon (cc @soerenthomsen ) and report back.

[jbusecke]

Hi @observingClouds, I am running into a problem with this, and get ModuleNotFoundError: No module named 'formatting'.

Where is the formatting package coming from? I was not able to see that in your requirements.txt, but I might be missing something.

Again, thank you so much for sharing your code, this is less than trivial for me.

[observingClouds]

Hi @jbusecke, the formatting module comes from the pybtex-apa-style-package. It is confusing, I agree.

[soerenthomsen]

Thanks @observingClouds also from my side!

[jbusecke]

Huh, weird I did install pybtex-apa-style in my environment. But let me wipe and reinstall to confirm.

[jbusecke]

That solved it. I think an old pip version might be to blame here. Sorry for the confusion! Works like a charm now!