diff --git a/book/_toc.yml b/book/_toc.yml index abecdbf..c3263ab 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -25,6 +25,7 @@ parts: - file: syntax_exercises/010.md - file: syntax_exercises/011.md - file: syntax_exercises/012.md + - file: syntax_exercises/013.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/syntax_exercises/013.md b/book/syntax_exercises/013.md new file mode 100644 index 0000000..3cadb1a --- /dev/null +++ b/book/syntax_exercises/013.md @@ -0,0 +1,176 @@ + +# Exercise 13: Adding a Bibliography + +In this exercise, you will learn how to cite sources using the shared bibliography provided in this template, and how to control the citation style and reference formatting using `{cite}` roles and the `{bibliography}` directive. + +::::::{topic} Exercise objective +Can you cite references using different in-line styles and customise the way your bibliography appears? +:::::: + +```{tip} +Citing references properly gives credit to original authors and improves your writing. See the [JupyterBook guide on citations](https://jupyterbook.org/en/stable/content/citations.html) for full details. +```` + +## Adding an entry to the shared bibliography + +1. The TeachBooks template already includes a shared bibliography file (`references.bib`). Locate and open the file. You will see the following example entry: + +``` +@misc{jason_moore, + title={Learn Multibody Dynamics, SymPy}, + author={Moore, Jason}, + howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}}, + year={2023} +} +``` + +2. Add a new reference of your own. You can use a DOI, book title, or URL. + +```{tip} +You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.org). Paste a source URL or title, click **Cite**, and export as **BibTeX** to copy into `references.bib`. +``` + +## Citing sources using `{cite}` + +3. To reference a source in-line, use one of the `{cite}` roles. Try the following: + +```md +{cite:p}`jason_moore` +``` + +4. You can also use other variants of `{cite}` depending on the style you want. Try adding the following to your Markdown file and see how the output differs: + +* `{cite:p}` +* `{cite:t}` +* `{cite:ps}` +* `{cite:ts}` + +```{dropdown} Hint: What to expect when you render these +:class: hint + +Here’s how the citation will appear for the example in the shared bibliography: + +- `{cite:p}` → **Parenthetical citation** + → [Moore, 2023] + +- `{cite:t}` → **Textual citation** + → Moore [2023] + +- `{cite:ps}` → **Parenthetical, full authors** + → [Moore, 2023] + +- `{cite:ts}` → **Textual, full authors** + → Moore [2023] + +``` + +## Displaying the bibliography + +5. To show the list of cited references at the end of the page, use the `{bibliography}` directive. In this template, the bibliography is already added to the [page](../references.md): + +````md +```{bibliography} +``` +```` + +`````{admonition} Avoiding duplicate citation warnings +:class: warning + +If you use `{bibliography}` in multiple files, you might see warnings about duplicate citations when building your book. To avoid this, restrict the bibliography to only show references cited in the current page by adding a `:filter:` option: + +````md +```{bibliography} +:filter: docname in docnames +``` + +```` + +This ensures only local references are shown, and avoids build-time warnings. +````` + + +## Customising citation styles + + +6. You can change the **reference style** (how citations appear in your text) by editing the `_config.yml` file in your book folder. Add or modify the following section, and see how the referece style changes. + +```yaml +sphinx: + config: + bibtex_reference_style: author_year +``` + +7. Try replacing `author_year` with the following and see how the citation outputs change: + +* `author_year` +* `label` +* `super` +* `number` + +```{dropdown} Hint: What each reference style will look like +:class: hint + +Heres's how each style will appear for the example in the shared bibliography: + +- `author_year` → Moore (2023) +- `label` → [jason_moore] +- `super` → ¹ +- `number` → [1] + +``` + +8. You can also change the **bibliography style** (how the reference list is formatted) using the `:style:` option in the `{bibliography}` directive. Try replacing the style with the following, and see how the bibliography style changes. + +````md +```{bibliography} +:style: unsrt +``` + +```` + +9. Experiment with the following different styles, and see how the bibliography style changes: + +- `alpha` +- `plain` +- `unsrt` +- `unsrtalpha` + +```{dropdown} Hint: What each bibliography style looks like +:class: hint + +Heres's how each style will appear for the example in the shared bibliography: + +- `alpha` → References labelled as [Knu84], sorted by author/year +- `plain` → References numbered [1], sorted by author/year +- `unsrt` → Numbered [1], in order of appearance in the text +- `unsrtalpha` → Alphanumeric like [Knu84], but in order of appearance + +``` + + +```{admonition} Bibliography style vs. Reference style +:class: note + +- **Reference style** controls how citations look in your text (e.g., [1] vs. (Author, Year)). +- **Bibliography style** controls how the reference list is formatted (e.g., sorted, numbered, APA). +``` + +10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +11. Add a commit message. + +12. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +13. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand: +- How to add a new reference to the shared `references.bib` file. +- How to use `{cite}` roles to control in-line citation appearance. +- How to change the citation style in `_config.yml`. +- How to display the bibliography with `{bibliography}`. +``` +