diff --git a/book/_static/apastyle.css b/book/_static/apastyle.css new file mode 100644 index 00000000..cea8eedc --- /dev/null +++ b/book/_static/apastyle.css @@ -0,0 +1,3 @@ +span.label { + display:none; +} diff --git a/book/features/_ext.zip b/book/features/_ext.zip deleted file mode 100644 index 34e2f8fd..00000000 Binary files a/book/features/_ext.zip and /dev/null differ diff --git a/book/features/apa.md b/book/features/apa.md index d2ece835..aad0ff9a 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -14,11 +14,13 @@ This page is useful for user type 4 and 5. # APA References ```{note} -This feature is 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`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more. +This feature is 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`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the README in the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17?pane=info) to learn more. The instructions provided here will work under conventional usage with Jupyter Book (e.g., `jupyter book build book`). A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)). + +_Update, October 21, 2025:_ a new fix was necessitated due to dependency issues with docutils making it no longer necessary to pin this package. See [PR 207 of the Manual for a description](https://github.com/TeachBooks/manual/pull/207). ``` ## Introduction @@ -28,34 +30,33 @@ Do you include references in your book, but you're tired of the default options 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 +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: +Download this zip-file [`apa_config.zip`](apa_config.zip), which contains the necessary files, located in _two_ subdirectories: `_ext` and `_static`. Unzip and place the contents in the root of your book directory so that it looks like the schematic here: ``` book ├── _ext/ │ ├── pybtexapastyle/ │ ├── apastyle.py -│ ├── bracket_citation_style.py +│ └── bracket_citation_style.py +├── _static/ +| ├── ... +│ └── apastyle.css ├── _config.yml ├── _toc.yml ├── requirements.txt ├── ``` -**Step 2: Add to `requirements.txt`** +Note that you may or may not already have a `_static` subdirectory, to which the file `apastyle.css` should be added. -Add a specific version of `docutils` to your requirements file: -``` -docutils==0.17.1 -``` +**Step 2: Enable in `_config.yml`** -**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`. This enables the (local) extension. -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: @@ -98,8 +99,8 @@ The extension is based on [`pybtex`](https://pybtex.org/), which is a BibTeX-com 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. +The need to include a CSS file is an easy solution to the issue where empty brackets `[]` are left on the references page (to try it, simply delete `apastyle.css`). ## 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! +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 the README of this [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17?pane=info). If you've ideas or questions, please reach out to us at info@teachbooks.io! diff --git a/book/features/apa_config.zip b/book/features/apa_config.zip new file mode 100644 index 00000000..b8007bbe Binary files /dev/null and b/book/features/apa_config.zip differ diff --git a/requirements.txt b/requirements.txt index 5d664df9..b96ca4cd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,6 +3,4 @@ sphinx-inline-tabs git+https://github.com/TeachBooks/TeachBooks-Favourites -teachbooks-sphinx-grasple - -docutils==0.17.1 +teachbooks-sphinx-grasple \ No newline at end of file