Package note: A static copy of this project exists on code.usgs.gov as the official release. The dynamic, living version of this project exists on GitHub at https://github.com/DOI-USGS/quarto-utils. The code.usgs.gov page will be updated with major releases with active development occuring on the GitHub repo.
Point of contact: Michael N. Fienen (mnfienen@usgs.gov)
Digital Object Identifier (DOI): https://doi.org/10.5066/P1GZPONT
Suggested Citation:
Fienen MN, Erickson RA. 2024. quarto-utils U.S. Geological Survey software release. Reston, Va., https://doi.org/10.5066/P1GZPONT.
Authors' ORCID nos.:
- Michael N. Fienen, 0000-0002-7756-4651
- Richard A. Erickson, 0000-0003-4649-482X
This python package works with Quarto MarkDown files to allow authors to supply dois for references while writing a document. Tools in this utilities package provide the ability to automatically query https://doi.org to return valid BiBTeX entries from dois.
Further utilities allow users to supply a list of dois, look up the BiBTeX entries, and update them into a new or existing BiBTeX file.
Finally, this package allows authors to compose Quarto MarkDown documents (.qmd files) using tagged dois as references. From these, the code replaces such dois with valid BiBTeX references which are also downloaded into a .bib file.
The jupyter notebook in /qtils/examples/examples.ipynb includes example applications of all the functions in the package.
This code will work with python 3.10 and greater with requests and text-unidecode packages (optional additional packages include jupyter notebook to run the notebook example and pytest to evaluate the tests).
To install, download this repo (such as git clone ...) and then run python setup.py install (or possibly python3 depending upon your local path configurations).
Department of Interior users may experience SSL certificate errors due to The site https://code.usgs.gov/usgs/best-practices/-/blob/master/ssl/WorkingWithinSSLIntercept.md?ref_type=heads provides some best practices for working with these security settings.
This repository contains a Quarto-based template for the Journal of Fish and Wildlife Management. To support this, the following files are located here:
README.mdis this file.LICENSE.mdis the Official USGS License.code.jsonis the code metadata.CONTRIBUTING.mddescribes how to contribute to this project.DISCLAIMER.mdis the standard USGS disclaimer..gitignoreis a file telling git which files to not track.cia folder for automated testing of this repository and contains ayamlfile.quarto-utilsa folder with the Python package an examples. This includes anexamplesfolder andtestfolder.setup.pyis a Python file for the package.
This template assumes the user knows, or at least wants to learn, how to use Markdown-based text programs such as Quarto. Knowing basic Markdown commands will help. Additionally, knowing LaTeX will assist in helping with advanced formatting.
The test.qmd and example.dois.qmd include references that Fienen created to demonstrate the package.
The content of the example is not meaningful, but the references are real - just inasmcuh as they can be pulled from the web.
test.qmd becomes test.updated.qmd after processing and the second file should be rendered as a Quarto file.
References in a bib files often require manual formatting.
For example, proper nouns like Mississippi River may need an extra {} to be capitalized, for example title = {{Mississippi River:} my story on {Old Man River}} to keep "Mississippi River" and "Old Man River capitalized.
The automatic references also often do not have correct capitalization and these may need to be changed by the user.
This code takes minimal run time (< 1 minute) under most situations.
- In some cases, special characters (such as em-dash or en-dash) in BiBTeX will be encoded as short character strings when written to the bib file. These characters will be seen on render or may crash quarto rendering. Users are advised to inspect references after they are downloaded.
- Some DOIs contain the underscore character (
_) and this cause this package to not find any new DOIs or otherwise fail. If this occurs, use\_doirather than_doito tag your DOIs in the Quarto file.
We thank the U.S. Geological Survey Biological Threats and Invasive Species Research Program and U.S. Geological Survey Water Mission Area Integrated Information Dissemination Division for funding. Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government. The findings and opinions expressed in this manuscript are those of the authors and do not necessarily represent the views of the US Fish and Wildlife Service.