Merge pull request #79 from TeachBooks/bibliography_exercise

Bibliography exercise

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

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}`.
+```
+