diff --git a/.gitignore b/.gitignore index 72818e9..1d59fdc 100644 --- a/.gitignore +++ b/.gitignore @@ -135,3 +135,6 @@ _contents/ # Jupyterlite _output/ book/.jupyterlite.doit.db + +# TeachBooks +**.teachbooks/ \ No newline at end of file diff --git a/book/_toc.yml b/book/_toc.yml index 1f8a2c8..27aa967 100644 --- a/book/_toc.yml +++ b/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 diff --git a/book/features/_ext.zip b/book/features/_ext.zip new file mode 100644 index 0000000..34e2f8f Binary files /dev/null and b/book/features/_ext.zip differ diff --git a/book/features/apa.md b/book/features/apa.md new file mode 100644 index 0000000..dfc20b3 --- /dev/null +++ b/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 +├── +``` + +**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! \ No newline at end of file diff --git a/book/references.bib b/book/references.bib index 865406e..2182ee7 100644 --- a/book/references.bib +++ b/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} } \ No newline at end of file