Jupyter-book: 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...).