diff --git a/README.md b/README.md index 148eabc..97b1692 100644 --- a/README.md +++ b/README.md @@ -50,3 +50,34 @@ In your markdown files: 2. Add `\bibliography`, or the value of `bib_command`, to the doc you want your references rendered (if `bib_by_default` is set to true this is automatically applied for every page). 3. (Optional) Add `\full_bibliography`, or the value of `full_bib_command`, to where you want the full bibliography rendered. *Note*: This is currently not working properly, since this plugin can't dictate the order in which files are processed. The best way to ensure the file with the full bibliography gets processed last is to use numbers in front of file/folder names to enforce the order of processing, IE: `01_my_first_file.md` 4. (Optional) Configure the `csl_file` option to dictate the citation text formatting. + +## Debugging + +You may wish to use the verbose flag in mkdocs (`-v`) to log debug messages. You should see something like this + +```bash +(...) +DEBUG - Parsing bibtex file 'docs/bib/papers.bib'... +INFO - SUCCESS Parsing bibtex file 'docs/bib/papers.bib' +DEBUG - Downloading CSL file from URL https://raw.githubusercontent.com/citation-style-language/styles/master/apa-6th-edition.csl to temporary file... +INFO - CSL file downladed from URL https://raw.githubusercontent.com/citation-style-language/styles/master/apa-6th-edition.csl to temporary file () +(...) +DEBUG - Reading: publications.md +DEBUG - Running 2 `page_markdown` events +DEBUG - Formatting all bib entries... +DEBUG - --Converting bibtex entry 'foo2019' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11 +DEBUG - --SUCCESS Converting bibtex entry 'foo2019' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11 +DEBUG - --Converting bibtex entry 'bar2024' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11 +DEBUG - --SUCCESS Converting bibtex entry 'bar2024' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11 +INFO - SUCCESS Formatting all bib entries +DEBUG - Replacing citation keys with the generated ones... +DEBUG - --Rendering citation inline for '[@foo2019]'... +DEBUG - ----Converting pandoc citation key '[@foo2019]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'... +DEBUG - ----SUCCESS Converting pandoc citation key '[@foo2019]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib' +DEBUG - --SUCCESS Rendering citation inline for '[@foo2019]' +DEBUG - --Rendering citation inline for '[@bar2024]'... +DEBUG - ----Converting pandoc citation key '[@bar2024]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'... +DEBUG - ----SUCCESS Converting pandoc citation key '[@bar2024]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib' +DEBUG - --SUCCESS Rendering citation inline for '[@bar2024]' +DEBUG - SUCCESS Replacing citation keys with the generated ones +``` diff --git a/src/mkdocs_bibtex/plugin.py b/src/mkdocs_bibtex/plugin.py index 36f777c..76e1572 100644 --- a/src/mkdocs_bibtex/plugin.py +++ b/src/mkdocs_bibtex/plugin.py @@ -15,6 +15,7 @@ format_simple, insert_citation_keys, tempfile_from_url, + log, ) @@ -63,7 +64,7 @@ def on_config(self, config): is_url = validators.url(self.config["bib_file"]) # if bib_file is a valid URL, cache it with tempfile if is_url: - bibfiles.append(tempfile_from_url(self.config["bib_file"], ".bib")) + bibfiles.append(tempfile_from_url("bib file", self.config["bib_file"], ".bib")) else: bibfiles.append(self.config["bib_file"]) elif self.config.get("bib_dir", None) is not None: @@ -74,7 +75,9 @@ def on_config(self, config): # load bibliography data refs = {} for bibfile in bibfiles: + log.debug(f"Parsing bibtex file {bibfile!r}...") bibdata = parse_file(bibfile) + log.info(f"SUCCESS Parsing bibtex file {bibfile!r}") refs.update(bibdata.entries) self.bib_data = BibliographyData(entries=refs) @@ -82,7 +85,7 @@ def on_config(self, config): # Set CSL from either url or path (or empty) is_url = validators.url(self.config["csl_file"]) if is_url: - self.csl_file = tempfile_from_url(self.config["csl_file"], ".csl") + self.csl_file = tempfile_from_url("CSL file", self.config["csl_file"], ".csl") else: self.csl_file = self.config.get("csl_file", None) @@ -200,10 +203,12 @@ def format_citations(self, cite_keys): entries[key] = self.bib_data.entries[key] # 3. Format entries + log.debug("Formatting all bib entries...") if self.csl_file: self.all_references.update(format_pandoc(entries, self.csl_file)) else: self.all_references.update(format_simple(entries)) + log.info("SUCCESS Formatting all bib entries") # 4. Construct quads quads = [ diff --git a/src/mkdocs_bibtex/utils.py b/src/mkdocs_bibtex/utils.py index eb1fcb9..2476af4 100644 --- a/src/mkdocs_bibtex/utils.py +++ b/src/mkdocs_bibtex/utils.py @@ -1,3 +1,4 @@ +import logging import re import requests import tempfile @@ -6,11 +7,17 @@ from pathlib import Path import pypandoc +from mkdocs.utils import warning_filter + from pybtex.backends.markdown import Backend as MarkdownBackend from pybtex.database import BibliographyData from pybtex.style.formatting.plain import Style as PlainStyle +log = logging.getLogger("mkdocs.plugins.mkdocs-bibtex") +log.addFilter(warning_filter) + + def format_simple(entries): """ Format the entries using a simple built in style @@ -25,6 +32,7 @@ def format_simple(entries): backend = MarkdownBackend() citations = OrderedDict() for key, entry in entries.items(): + log.debug(f"Converting bibtex entry {key!r} without pandoc") formatted_entry = style.format_entry("", entry) entry_text = formatted_entry.text.render(backend) entry_text = entry_text.replace("\n", " ") @@ -32,6 +40,7 @@ def format_simple(entries): citations[key] = ( entry_text.replace("\\(", "(").replace("\\)", ")").replace("\\.", ".") ) + log.debug(f"SUCCESS Converting bibtex entry {key!r} without pandoc") return citations @@ -47,12 +56,16 @@ def format_pandoc(entries, csl_path): """ pandoc_version = tuple(int(ver) for ver in pypandoc.get_pandoc_version().split(".")) citations = OrderedDict() + is_new_pandoc = pandoc_version >= (2, 11) + msg = "pandoc>=2.11" if is_new_pandoc else "pandoc<2.11" for key, entry in entries.items(): bibtex_string = BibliographyData(entries={entry.key: entry}).to_string("bibtex") - if pandoc_version >= (2, 11): + log.debug(f"--Converting bibtex entry {key!r} with CSL file {csl_path!r} using {msg}") + if is_new_pandoc: citations[key] = _convert_pandoc_new(bibtex_string, csl_path) else: citations[key] = _convert_pandoc_legacy(bibtex_string, csl_path) + log.debug(f"--SUCCESS Converting bibtex entry {key!r} with CSL file {csl_path!r} using {msg}") return citations @@ -102,12 +115,16 @@ def _convert_pandoc_citekey(bibtex_string, csl_path, fullcite): with open(bib_path, "wt", encoding="utf-8") as bibfile: bibfile.write(bibtex_string) + log.debug(f"----Converting pandoc citation key {fullcite!r} with CSL file {csl_path!r} and Bibliography file" + f" '{bib_path!s}'...") markdown = pypandoc.convert_text( source=fullcite, to="markdown-citations", format="markdown", extra_args=["--citeproc", "--csl", csl_path, "--bibliography", bib_path], ) + log.debug(f"----SUCCESS Converting pandoc citation key {fullcite!r} with CSL file {csl_path!r} and " + f"Bibliography file '{bib_path!s}'") # Return only the citation text (first line(s)) # remove any extra linebreaks to accommodate large author names @@ -207,6 +224,8 @@ def insert_citation_keys(citation_quads, markdown, csl=False, bib=False): markdown (str): the modified Markdown """ + log.debug("Replacing citation keys with the generated ones...") + # Renumber quads if using numbers for citation links grouped_quads = [list(g) for _, g in groupby(citation_quads, key=lambda x: x[0])] @@ -216,6 +235,7 @@ def insert_citation_keys(citation_quads, markdown, csl=False, bib=False): # if cite_inline is true, convert full_citation with pandoc and add to replacement_citaton if csl and bib: + log.debug(f"--Rendering citation inline for {full_citation!r}...") # Verify that the pandoc installation is newer than 2.11 pandoc_version = pypandoc.get_pandoc_version() pandoc_version_tuple = tuple(int(ver) for ver in pandoc_version.split(".")) @@ -231,9 +251,12 @@ def insert_citation_keys(citation_quads, markdown, csl=False, bib=False): # Make sure inline citations doesn't get an extra whitespace by # replacing it with whitespace added first markdown = markdown.replace(f" {full_citation}", replacement_citaton) + log.debug(f"--SUCCESS Rendering citation inline for {full_citation!r}") markdown = markdown.replace(full_citation, replacement_citaton) + log.debug("SUCCESS Replacing citation keys with the generated ones") + return markdown @@ -256,7 +279,8 @@ def format_bibliography(citation_quads): return "\n".join(bibliography) -def tempfile_from_url(url, suffix): +def tempfile_from_url(name, url, suffix): + log.debug(f"Downloading {name} from URL {url} to temporary file...") for i in range(3): try: dl = requests.get(url) @@ -268,6 +292,7 @@ def tempfile_from_url(url, suffix): file = tempfile.NamedTemporaryFile(mode="wt", encoding="utf-8", suffix=suffix, delete=False) file.write(dl.text) file.close() + log.info(f"{name} downladed from URL {url} to temporary file ({file})") return file.name except requests.exceptions.RequestException: # pragma: no cover