From 6c399f1c93472aa0fb3fd03a60f23cad90834de6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 9 Dec 2024 15:24:18 +0100 Subject: [PATCH 1/4] Added page on apa extension --- book/_toc.yml | 1 + book/features/_ext.zip | Bin 0 -> 10416 bytes book/features/apa.md | 69 +++++++++++++++++++++++++++++++++++++++++ book/references.bib | 7 +++++ 4 files changed, 77 insertions(+) create mode 100644 book/features/_ext.zip create mode 100644 book/features/apa.md 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 0000000000000000000000000000000000000000..34e2f8fde9bb50d1e4b06e092002ef828b849459 GIT binary patch literal 10416 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 +``` + +**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}`jason_moore` which shows up on the [references page too](../references.md) + +### Known issue +During the build, warning will be raised with `... WARNING: duplicate label for keys ...`. In most cases, these warnings can be ignored. + +## Contribute +This tool needs to be developed further to make it into a proper sphinx-extension. The process is described here: 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 From ff13a5dae52886ea0a989831c91532de2cc2e525 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 9 Dec 2024 15:31:26 +0100 Subject: [PATCH 2/4] Update apa.md --- book/features/apa.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/book/features/apa.md b/book/features/apa.md index a0b1a81..7a45e42 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -5,19 +5,12 @@ This page is useful for user type 4 and 5. ``` -{bdg-primary}`(To be) Sphinx Extension` +{bdg-primary}`(To be converted into) Sphinx Extension` ## Introduction This extension allows you to have APA formatting which is not a default option. - - -## How does it work? -Sphinx extension that inverts the colors of images and iframes in dark mode but keeps the colours recognizable. This is particularly useful for graphs in which a certain colour is mentioned in accompanying text. Item are not converted if they are marked with the `dark-light` class (recommended for photos). - -In more detail, the colors of the element are inverted, then the hue of the colors is shifted by 180 degrees, so the inverted colors change to their complementary hues. This flips the brightness and contrast, while keeping the hue somewhat recognizable (so a blue line will be a blue line in both ligth and dark mode). Black and white stay inverted (so white becomes black, and black becomes white), because they don’t have a hue. After this, the element blends with the background, making similar colors appear dark and very different colors appear bright. The overall effect creates high contrast between the element and the background, depending on their colors. - ## Installation To use APA-references, a python package needs to be manually loaded into your book @@ -60,7 +53,9 @@ sphinx: ``` ## Usage -All references are now made in APA-style. See for example this reference: {cite}`jason_moore` which shows up on the [references page too](../references.md) +All references are now made in APA-style. See for example this reference: {cite}`jason_moore` which shows up on the [references page](../references.md) too. + +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. From 5f2e9a5be88ef5d3810149a87083cce0a146fc61 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 9 Dec 2024 16:21:42 +0100 Subject: [PATCH 3/4] ignore temp .teachbooks --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) 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 From 3d523d067d62ccd9897b038198f348f65f63ac62 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 9 Dec 2024 16:21:53 +0100 Subject: [PATCH 4/4] robert adds to apa page --- book/features/apa.md | 51 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/book/features/apa.md b/book/features/apa.md index 7a45e42..dfc20b3 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -1,4 +1,4 @@ -# APA references +# APA References ```{admonition} User types :class: tip @@ -7,16 +7,26 @@ 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 -This extension allows you to have APA formatting which is not a default option. +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 python package needs to be manually loaded into your book +To use APA-references, a set of Python files need to be manually loaded into your book -**Step 1: Add zip file to book root** +**Step 1: files to root directory of your book** -Add the zip-file [`_ext.zip`](_ext.zip) to the root of your file so that it looks like: +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 @@ -53,12 +63,35 @@ sphinx: ``` ## Usage -All references are now made in APA-style. See for example this reference: {cite}`jason_moore` which shows up on the [references page](../references.md) too. + +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. +### 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. The process is described here: 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 + +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