Merge pull request #915 from sappelhoff/fix/pdf/internal_links

[INFRA] PDF version of spec: fix handling of internal links

.circleci/config.yml

@@ -201,12 +201,4 @@ workflows:
           filters:
             branches:
               only: master
-      # Ensure that build_docs_pdf always runs last, so that we can use the CircleCI API link for the "latest" artifact
-      # https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master
-      - build_docs_pdf:
-          requires:
-            - build_docs
-            - linkchecker
-            - github-changelog-generator
-            - remark
-            - Changelog-bot
+      - build_docs_pdf

.github/workflows/main.yml → .github/workflows/redirect_circleci_artifacts.yml

@@ -5,8 +5,13 @@ jobs:
     name: Run CircleCI artifacts redirector
     steps:
       - name: GitHub Action step
+        id: step1
         uses: larsoner/circleci-artifacts-redirector-action@master
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           artifact-path: 0/bids-spec.pdf
           circleci-jobs: build_docs_pdf
+          job-title: Check the rendered PDF version here!
+      - name: Check the URL
+        run: |
+          curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA

.gitignore

@@ -4,6 +4,7 @@ site/
 venvs
 
 pdf_build_src/bids-spec.pdf
+pdf_build_src/bids-spec_pandoc_log.json
 pdf_build_src/src_copy
 
 # JS/NPM

Release_Protocol.md

@@ -95,8 +95,8 @@ Important note: The pull request title **must** be named "REL: vX.Y.Z" (for exam
 
 **This will open a period of discussion for 5 business days regarding if we are ready to release.**
 
-Minor revisions may be made using GitHub's [suggestion
-feature](https://help.github.com/en/articles/incorporating-feedback-in-your-pull-request).
+Minor revisions may be made using GitHub's
+[suggestion feature](https://help.github.com/en/articles/incorporating-feedback-in-your-pull-request).
 For larger changes, pull requests should be made against `master`.
 
 **Merging other pull requests during this period requires agreement among BIDS Maintainers.**
@@ -171,8 +171,8 @@ There are four components to the tag command:
 ### 8. Create a GitHub release
 
 Some GitHub processes may only trigger on a GitHub release, rather than a tag push.
-To make a GitHub release, go to the [Releases
-](https://github.com/bids-standard/bids-specification/releases) page:
+To make a GitHub release, go to the
+[Releases](https://github.com/bids-standard/bids-specification/releases) page:
 ![GH-release-1](release_images/GH-release_1.png "GH-release-1")
 
 Click [Draft a new release](https://github.com/bids-standard/bids-specification/releases/new):

pdf_build_src/README.md

@@ -9,7 +9,7 @@ The `pdf_build_src` directory contains the scripts and `.tex` files required to
 For the pdf build to be successful, the following need to be installed:
 
 - Python 3.6 or higher
-- Numpy
+- several Python packages (see `/requirements.txt`)
 - pandoc
 - Latest version of LaTeX: By default, Pandoc creates PDFs using LaTeX.
   Because a full MacTeX installation uses four gigabytes of disk space,
@@ -47,3 +47,5 @@ additional tex files are used with options offered by pandoc.
 - `pandoc_script.py` - Prepares and runs the final pandoc command through the `build_pdf.sh` script
 
 - `build_pdf.sh` - Shell script that organizes the directory structure and runs the above two python scripts
+
+- `check_pandoc_log.py` - Script that checks the pandoc log for warnings that should be raised as errors in the continuous integration services

pdf_build_src/build_pdf.sh

@@ -10,9 +10,14 @@ python3 process_markdowns.py
 cp pandoc_script.py header.tex cover.tex header_setup.tex src_copy/src
 
 # run pandoc_script from src_copy directory
-cd src_copy/src
+pushd src_copy/src
 python3 pandoc_script.py
 mv bids-spec.pdf ../..
+mv bids-spec_pandoc_log.json ../..
+popd
+
+# Do a check on the pandoc log file
+python3 check_pandoc_log.py
 
 # delete the duplicated src directory
 rm -rf src_copy

pdf_build_src/check_pandoc_log.py

@@ -0,0 +1,29 @@
+"""Inspect the pandoc log for warnings that should be raised as errors."""
+
+# %%
+import json
+
+# see pandoc_script.py
+LOGFILE = "bids-spec_pandoc_log.json"
+
+# read the log file
+with open(LOGFILE, "r") as fin:
+    logs = json.load(fin)
+
+# go through the logs (list of dicts)
+duplicate_link_refs = []
+for log_dict in logs:
+
+    # Check for DuplicateLinkReference
+    logtype = log_dict.get("type", None)
+    logverbosity = log_dict.get("verbosity", None)
+
+    if logtype == "DuplicateLinkReference" and logverbosity == "WARNING":
+        duplicate_link_refs.append(log_dict)
+
+# raise errors if appropriate
+if len(duplicate_link_refs) > 0:
+    msg = "\n\nFound duplicate link references. Please make them unique.\n"
+    for log_dict in duplicate_link_refs:
+        msg += "\n" + json.dumps(log_dict, indent=4)
+    raise RuntimeError(msg)

pdf_build_src/pandoc_script.py

@@ -7,14 +7,15 @@
 import subprocess
 
 
-def build_pdf(filename):
+def build_pdf(filename="bids-spec.pdf", logfile="bids-spec_pandoc_log.json"):
     """Construct command with required pandoc flags and run using subprocess.
 
     Parameters
     ----------
     filename : str
-        Name of the output file.
-
+        Name of the output file. Defaults to "bids-spec.pdf".
+    logfile : str
+        Name of the log file. Defaults to "bids-spec_pandoc_log.json".
     """
     # Files that are not supposed to be built into the PDF
     EXCLUDE = ["./index.md", "./schema/README.md", "./pregh-changes.md"]
@@ -38,7 +39,8 @@ def build_pdf(filename):
         '--include-in-header=./header.tex',
         '--include-in-header=./header_setup.tex',
         '--pdf-engine=xelatex',
-        '--output={}'.format(filename),
+        f'--log={logfile}',
+        f'--output={filename}',
     ]
 
     # location of this file: This is also the working directory when
@@ -65,4 +67,4 @@ def build_pdf(filename):
 
 
 if __name__ == "__main__":
-    build_pdf('bids-spec.pdf')
+    build_pdf()