Added several log messages. (#224)

* Added several log messages. Fixed #223 * Improved log and added section in readme * Update src/mkdocs_bibtex/utils.py 1 * Update src/mkdocs_bibtex/plugin.py 1 * Update src/mkdocs_bibtex/plugin.py * Update src/mkdocs_bibtex/utils.py --------- Co-authored-by: Sylvain MARIE <[email protected]> Co-authored-by: Shyam Dwaraknath <[email protected]>
shyamd · Feb 2, 2024 · ab83940 · ab83940
1 parent 9ee97d1
commit ab83940
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 4 deletions.
diff --git 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 (<tempfile._TemporaryFileWrapper object at 0x00000203E4F2F650>)
+(...)
+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
@@ -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,15 +75,17 @@ 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)
 
         # 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
@@ -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,13 +32,15 @@ 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", " ")
         # Local reference list for this file
         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