APA References

APA References#

Introduction#

Do you include references in your book, but you’re tired of the default options available in a TeachBook / Jupyter Book v1? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?

There is a solution! This extension allows you to have APA formatting in your book.

Installation#

To use APA-references, install the Sphinx-APA-References extension by following these two steps:

Step 1: Install the Package

Install the module sphinx-apa-references package using pip:

pip install sphinx-apa-references

Step 2: Add to requirements.txt

Make sure that the package is included in your project’s requirements.txt to track the dependency:

sphinx-apa-references

Step 3: Enable in _config.yml

In your _config.yml file, add the extension to the list of Sphinx extra extensions (important: underscore, not dash this time) and specify the location of your bib file (note indentation of the bibtex file path specification; any number of bib files are allowed):

sphinx: 
    extra_extensions:
        .
        .
        .
        - sphinx_apa_references
        .
        .
        .
bibtex_bibfiles: "<path_to_bib_file>/references.bib"

Usage#

All references are now made in APA-style. Here are five examples how to create a citation in APA style:

Syntax

Result with 1 author

Result with many authors

Explanation

{cite:t}

Moore (2023)

Author et al. (2013)

Textual citation

{cite:p}

(Moore, 2023)

(Author et al., 2013)

Parenthetical citation

{cite}

(Moore, 2023)

(Author et al., 2013)

Same as {cite:p}

{cite:ts}

Moore (2023)

Author, Writer, Novelist, and Cowriter (2013)

Same as {cite:t}, but without abbreviation of authors

{cite:ps}

(Moore, 2023)

(Author, Writer, Novelist, and Cowriter, 2013)

Same as {cite:p}, but without abbreviation of authors

For more options on the in-line citation style, see https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style.

The references section at the end of your book will also be formatted in APA style:

Example of APA References

Duplicate label warning#

You might encounter a warning during the build process that has this structure:

<filename>:<lineno>: WARNING: duplicate label "<authors>, <year>" for keys "<key1>" and "<key2>"

This is might have different cause, but often it is because two different references have the same author(s) and the same year. A common solution is to add letters to the year in the .bib file, like this:

@misc{launch_buttons,
  author = {{TeachBooks}},
  title = {Custom launch buttons},
  url = {https://github.com/TeachBooks/Sphinx-launch-buttons},
  year = {2024a},
  note = {Retrieved December, 2024. BSD-3-Clause.},
}

@misc{nested,
  author = {{TeachBooks}},
  title = {Git workflow: Share content between book},
  url = {https://github.com/TeachBooks/Nested-Books},
  year = {2024b},
  note = {Retrieved December, 2024. CC BY 4.0.},
}

This does negate the automatic ordering of references by the order authors > year > title, so our advice is to only use this solution when the bibliography contains duplicate author-year combinations ánd the bibliography is final. That way the you can use the sorted order with warnings to determine the correct letters to add to the years.

Implementation#

The extension is based on pybtex, which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins.

Although some customization is possible with the standard Jupyter Book v1 features, as described here, this extension implements a complete APA style, as well as enforcing round brackets (like this).

Previous implementation#

APA referencing was previously implemented by including a local extension in a book subdirectory _ext (described here). To upgrade, once this Sphinx extension is implemented in your book, the local extension files in _ext can be deleted and the four lines indicated below removed from your _config.yml file:

sphinx:
  config:
    .
    .
    .
    bibtex_reference_style: author_year_round   # remove
    bibtex_default_style: myapastyle            # remove
    .
    .
    .
  local_extensions:
    apastyle: _ext/                             # remove
    bracket_citation_style: _ext/               # remove
Contents