Merge pull request #42 from TeachBooks/apa-extension-docs

Added page on apa extension

.gitignore

@@ -135,3 +135,6 @@ _contents/
 # Jupyterlite
 _output/
 book/.jupyterlite.doit.db
+
+# TeachBooks
+**.teachbooks/

book/_toc.yml

@@ -69,6 +69,7 @@ parts:
       - file: external/JupyterBook-Patches/README.md
       - file: external/Sphinx-TUDelft-theme/README.md
       - file: external/teachbooks-sphinx-tippy/README.md
+      - file: features/apa
     - file: features/students
       sections:
       - file: external/annotater/README.md

book/features/apa.md

@@ -0,0 +1,97 @@
+# APA References
+
+```{admonition} User types
+:class: tip
+This page is useful for user type 4 and 5.
+```
+
+{bdg-primary}`(To be converted into) Sphinx Extension`
+
+```{warning}
+The instructions provided here are stable, but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), there may be incompatibility with other features. For example, the draft-release workflow does not work.
+
+We are actively working on improving this. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more.
+
+This page will be updated when a solution is available.
+```
+
+## Introduction
+
+Do you include references in your book, but you're tired of the default options available in Jupyter Book? 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, a set of Python files need to be manually loaded into your book
+
+**Step 1: files to root directory of your book**
+
+Download this zip-file [`_ext.zip`](_ext.zip), which contains the necessary files, unzip it and place the contents in the root of your book directory so that it looks like the schematic here:
+
+```
+book
+├── _ext.zip
+│   ├── pybtexapastyle/
+│   ├── apastyle.py
+│   ├── bracket_citation_style.py
+├── _config.yml
+├── _toc.yml
+├── requirements.txt
+├── <book files>
+```
+
+**Step 2: Add to `requirements.txt`**
+
+Add a specific version of `docutils` to your requirements file:
+```
+docutils==0.17.1
+```
+
+**Step 3: Enable in `_config.yml`**
+
+In your `_config.yml` file, add a `bibtex_default_style`, `bybtex_reference_style` and the local extensions `apastyle` and `bracket_citation_style.py`
+```
+sphinx:
+  config:
+    ...
+    bibtex_default_style: myapastyle
+    bibtex_reference_style: author_year_round
+  local_extensions:
+    apastyle: _ext/
+    bracket_citation_style: _ext/
+  ...
+```
+
+## Usage
+
+All references are now made in APA-style. See for example this reference: {cite:t}`jason_moore` which shows up on the [references page](../references.md) too. The form of the citation looks like this:
+
+```
+{cite:t}`jason_moore`
+```
+
+Here are three examples for making citations:
+
+| Syntax | Result |
+| :---: | :---: |
+|`{cite:t}` | {cite:t}`jason_moore` |
+|`{cite:p}`| {cite:p}`jason_moore` |
+|`{cite}`| {cite}`jason_moore` |
+
+For more options on the in-line citation style, see https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style.
+
+### Known Issue
+
+During the build, warning will be raised with `... WARNING: duplicate label for keys ...`. In most cases, these warnings can be ignored. As noted above, the book will not build references properly 
+
+## Implementation
+
+The extension is based on [`pybtex`](https://pybtex.org/), which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins. 
+
+Although some customization is possible with the standard Jupyter Book features, [as described here](https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this).
+
+The need to enforce `docutils==0.17.1` version is the only known solution to the issue where empty brackets `[]` are left on the references page.
+
+## Contribute
+
+This tool needs to be developed further to make it into a proper sphinx-extension (and/or an independent `pybtext` plugin). The process is described in this [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17). If you've ideas or questions, please reach out to us at info@teachbooks.io!

book/references.bib

@@ -4,4 +4,11 @@
   institution ={Delft University of Technology},
   howpublished={\url{https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion}},
   year={2024}
+}
+
+@misc{jason_moore,
+  title={Learn Multibody Dynamics, SymPy},
+  author={Moore, Jason},
+  url={https://moorepants.github.io/learn-multibody-dynamics/sympy.html},
+  year={2023}
 }