Compile, sort, and verify the reference database at build time#42447
Compile, sort, and verify the reference database at build time#42447orlitzky wants to merge 6 commits into
Conversation
This is a sorted list of references from the existing bibliographic database page. By separating the references from the rest of the page, it becomes much easier to process (in particular, to sort) the list.
|
Documentation preview for this PR (built with commit dc3700b; changes) is ready! 🎉 |
orlitzky
force-pushed
the
build-references
branch
from
cc51508 to
6f1b1b3
Compare
This is a new script, meant to sort, verify, and "compile" a list of (ReST) citations into the main bibliographic reference page. It uses docutils to parse the citations that are now stored in a dedicated file. For the layout of the page, a template (passed as input to the script) is used instead. This will help keep our references in order, while avoiding the need to parse and/or generate a fully free-form ReST document.
We need a placeholder for the generated index.rst in the source tree during "meson setup", otherwise the documentation build won't expect one to be there after we generate it.
Add a custom_target() to run src/sage_docbuild/generate-references.py, generating the full reference database page from the database of references and a template. We no longer copyfile(index.rst) because that is now a placeholder.
We use it to parse/sort the references database.
orlitzky
force-pushed
the
build-references
branch
from
6f1b1b3 to
dc3700b
Compare
|
Should, e.g., |
I decided on case-sensitive within each letter group because it keeps the same authors together, so long as the labels are chosen consistently. For example: Case-sensitive:
versus case-insensitive:
I don't feel too strongly about it though. Whatever people want is fine. |
|
I would vote for case-insensitive because otherwise the distance between |
|
I just mentioned this on the mailing list because it can be considered a big change, maybe others will chime in. If not I'll just switch it to case-insensitive. |
|
I've been saying for years that references should come in .bib files, these can be processed just fine with sphinx. |
That would be much better in the long term, but we have thousands of existing entries that would need to be converted first. |
I agree with these points. @orlitzky changing this would be out of scope for this PR, but would this new setup make it possible to do some kind of hybrid system where the old references remain as they are (at least unless someone has the time to go through them), and new references are added to a .bib file? Then this script merges it all together into one |
It should be possible, sphinxcontrib-bibtex is using pybtex under the hood, and there is a pybtex-docutils package that looks like it does what we need. The example in its README shows it parsing a bibtex file (well, a string in this case), and then looping through the entries. |
4 participants
Build the main reference database page from a "database" containing only references, at build time.
src/doc/en/reference/references/index.rstto a template with@REFS_<LETTER>@placeholders for the content.index.rstbehind, so that the docbuild expects the generated one to (eventually) be there.src/sage_docbuild/generate-references.pyto "compile" the final page from the reference database and template.src/doc/en/reference/references/meson.buildto (re)build the references page as needed, when either the database or template changes.This approach has several advantages:
src/doc/reference-database.rstDocumentation shortcuts: