Toolsreq 8242 bibliography #28
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit adds some placeholder bibliographical information so that we can test on it and incorporate the jupyer book style of referencing into our script and workflow. Since our house style (Chicago) prefers footnote citations but allows for author-date, we're going to target author-date as it's the closest appropriate format. NOTE: I've included both a "bibliography" file in here for testing a book-wide bibliography, as well as an in-chapter bibliography, since both are valid in CMS.
delfanbaum
force-pushed
the
TOOLSREQ-8242-bibliography
branch
from
e8a9612 to
1714eb3
Compare
delfanbaum
force-pushed
the
TOOLSREQ-8242-bibliography
branch
2 times, most recently
from
25d9fbb to
8e1576d
Compare
This is a first pass at handling jupyter book-style bibliographies. There are a number of compromises made but we'll get to that. As a commit: * This adds tests around both end-of-book bibliographies as well as end-of-chapter and end-of-chapter-part-file bibliographies, as well as code to pass those tests. * There was a small refactor in the `chapter_processing`-type functions to yank out the code that ultimately went into `get_main_section()` to avoid duplication. A chapter-file bibliography gets added as its own section, so we needed a way to capture that and doing it in one function as opposed to in both the chapter and chapter part processing functions made more sense. * HTMLBook bibliographies are appendixes, so that data-type is added when the bib is a single file. * The actual handling of the bibliography happens in the `process_citations` function, which rips out the <dt> pointers and leaves only the <dd> citations. Handling the actual citations to these bibliographical references will come in a later commit. Some notes and caveats: * There is not a good way to reformat the citations in this script. The way to do it would be to modify the Bibtex formatting, but that feels outside the scope of our current work. This means that bibliographies will have to be worked on after intake; this feels like an OK compromise for the time being. Should we go down that path, there is some discussion [here](link), and related [here](other_link). * Since we don't really have a good way to modify the bibliographical entries themselves, we likewise don't have a great way to organize combined bibliographies from multiple chapter sub-files. Right now we're doing a sort of "dumb" combine, appending one to the other (i.e., we're not sorting them in any way). While we could do some list sorting, I'm not confident it would be good enough or that the data will be standard enough to really do that in a reliable way, so for now this compromise feels not _great_ but worthwhile. * As mentioned, handling for the citations themselves will come in a subsequent commit. Sadly, we're starting to get to the brittler points wherein I'm beginning to think that we ought to instead be writing some kind of a backend against Jupyter Book/Sphinx like we do for asciidoc, but we're in this far, so we'll just need to keep on top of Jupyter Book updates and be careful about targeted version(s). This commit tries to honor making the script "just work" while compromising enough that hopefully what work done here is relatively durable (i.e., not making too much assumptions about the formatting of things outside of the document structure itself, which _in theory_ is going to be relatively stable going forward. link: jupyter-book/jupyter-book#1090 other_link: mcmtroffaes/sphinxcontrib-bibtex#203 Update: check for existance of lis after processing Update: typo fix
Luckily, most of the code to handle this was already written, however we were targeting the <=0.11 version of Jupyter Book's way of handling cross references so now we're up-to-date. Basically we check if it's a bracketed reference (which appears to be always and only the case for bibliographical citations as far as I can tell) and handle it like we used to from there. This commit updated the test for this and the code to pass it. Update: made the if-check for it being a citation better.
delfanbaum
force-pushed
the
TOOLSREQ-8242-bibliography
branch
from
8e1576d to
2064ad8
Compare
nadamsoreilly
approved these changes
Jan 5, 2023
delfanbaum
added a commit
that referenced
this pull request
Jan 9, 2025
delfanbaum
added a commit
that referenced
this pull request
Jan 9, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds BASIC bibliography handling for Jupyter Book's preferred way of doing bibliographies. There are a number of compromises made, which are listed in the note of the second (meatiest) commit. That said, we've got a basic functionality that should be relatively easy to clean up after intake for the production editors, so I feel pretty OK about it.