admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update Manual page

Browse source
This commit is contained in:
Robert Lanzafame 2025-10-23 10:30:04 -07:00 • committed by GitHub
parent abe5f2206a
commit 58cfcc523c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 26 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
book/features/_ext.zip
View file

Binary file not shown.

39
book/features/apa.md
View file

@ -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
├── <book files>
```
**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:
@ -68,6 +69,18 @@ sphinx:
...
```
**Step 3: Enable in `_config.yml`**
In your `_config.yml` file, add a `_static` is listed under `html_static_path`. This ensures the CSS file is included.
```
sphinx:
config:
...
html_static_path: ["_static", ...]
...
```
## 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:
@ -98,8 +111,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!

BIN
book/features/apa_config.zip Normal file
View file

Binary file not shown.