pdf version specs

.circleci/config.yml

@@ -29,6 +29,22 @@ jobs:
           root: .
           paths: site
 
+  build_docs_pdf:
+    working_directory: ~/bids-specification/pdf_build_src
+    docker:
+      - image: danteev/texlive:TL2017
+    steps:
+      - checkout:
+          path: ~/bids-specification
+      - run: 
+          name: generate pdf version docs 
+          command: sh build_pdf.sh
+      - store_artifacts:
+          path: bids-spec.pdf
+      - run:
+          name: remove pdf version from repo
+          command: rm bids-spec.pdf
+
   linkchecker:
     docker:
       - image: yarikoptic/linkchecker:9.4.0.anchorfix1-1
@@ -57,7 +73,7 @@ jobs:
            working_directory: ~/build
            command: |
              if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then
-             github_changelog_generator --user bids-standard --project bids-specification --token ${CHANGE_TOKEN} --output ~/build/CHANGES.md --base ~/build/src/pregh-changes.md --header-label Changelog --no-issues --no-issues-wo-labels --no-filter-by-milestone --no-compare-link --pr-label ""
+             github_changelog_generator --user bids-standard --project bids-specification --token ${CHANGE_TOKEN} --output ~/build/CHANGES.md --base ~/build/src/pregh-changes.md --header-label "# Changelog" --no-issues --no-issues-wo-labels --no-filter-by-milestone --no-compare-link --pr-label ""
              cat ~/build/CHANGES.md
              mv ~/build/CHANGES.md ~/build/src/CHANGES.md
              else
@@ -144,6 +160,7 @@ workflows:
   search_build:
     jobs:
       - build_docs
+      - build_docs_pdf
       - linkchecker:
           requires:
             - build_docs

.gitignore

@@ -1 +1,3 @@
-site/
+site/
+node_modules/
+package-lock.json

pdf_build_src/README.md

@@ -0,0 +1,41 @@
+# pdf-version of BIDS specification 
+
+The `pdf_build_src` directory contains the scripts and tex files required to build a pdf document of the BIDS specification from multiple markdown files using the pandoc library. 
+
+Pandoc is command line tool which is also a Haskell library that converts files from one markup format to another. More here: https://pandoc.org/index.html
+
+## Requirements
+
+For the pdf build to be successful, the following need to be installed: 
+
+- Python 3.x 
+- pandoc 
+- Latest version of LaTeX: By default, Pandoc creates PDFs using LaTeX. Because a full MacTeX installation uses four gigabytes of disk space, pandoc recommends BasicTeX or TinyTeX and using the tlmgr tool to install additional packages as needed. 
+
+Installation instructions for both pandoc and LaTeX: https://pandoc.org/installing.html
+
+## Building pdf document
+
+Run the `build_pdf.sh` from the `pdf_build_src` with the command `sh build_pdf.sh` from the command line terminal 
+
+List of warnings are for missing characters like emojis while converting from markdown to pdf. Except for losing those characters in the final document, it doesn't affect the formatting or contents and therefore, can be ignored.
+
+## Technical Overview
+
+Pandoc comes with a plethora of options to format the resulting document. For building a pdf from multiple markdowns, a consolidated intermediate tex file is first built, which is then converted to a pdf document. To achieve the desired formatting in the final pdf, additional tex files are used with options offered by pandoc. 
+
+### Formatting files
+
+`listings_setup.tex` -  Listings is a LaTeX package used for typestting programming code in TeX. This file sets up the listings package to suit our needs and is used with the `--listings` option. 
+
+`cover.tex` - BIDS Logo is used as a cover page for the document. `cover.tex` is used with the option `--include-before-body`
+
+`header.tex` - Header tex file that's updated with the latest version number and date when `build_pdf.sh` is run. Used with the `-H` header option. 
+
+### Scripts
+
+`process_markdowns.py` - Script that processes markdown files in the `src` directory that are duplicated and modified for the needs of the pdf. 
+
+`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

pdf_build_src/build_pdf.sh

@@ -0,0 +1,16 @@
+# Shell script that runs process_markdowns.py and pandoc_script.py in sequence to build the pdf document
+
+# prepare the copied src directory 
+python3 process_markdowns.py
+
+# copy pandoc_script into the temp src_copy directory 
+cp pandoc_script.py header.tex cover.tex listings_setup.tex src_copy/src
+
+# run pandoc_script from src_copy directory 
+cd src_copy/src
+python3 pandoc_script.py
+mv bids-spec.pdf ../..
+cd ../..
+
+# delete the duplicated src directory
+rm -rf src_copy

pdf_build_src/cover.tex

@@ -0,0 +1,27 @@
+% adds the bids logo as the cover page of the pdf
+\begin{titlepage}
+
+\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here
+
+\center % Center everything on the page
+
+
+
+%----------------------------------------------------------------------------------------
+%	LOGO SECTION
+%----------------------------------------------------------------------------------------
+
+\includegraphics[width=0.6\textwidth]{images/BIDS_logo.jpg}\\[1cm] 
+
+%----------------------------------------------------------------------------------------
+%	TITLE SECTION
+%----------------------------------------------------------------------------------------
+
+\HRule \\[0.4cm]
+{ \huge \bfseries Brain Imaging Data Structure Specification}\\[0.4cm] % Title of your document
+\HRule \\[1.5cm]
+
+% \textsc{\large v1.2.1}\\[0.5cm]{\large 2019-08-14}\\[2cm]
+
+% \vfill % Fill the rest of the page with whitespace
+\textsc{\large v1.2.1}\\[0.5cm]{\large 2019-08-14}\\[2cm]\vfill\end{titlepage}

pdf_build_src/header.tex

@@ -0,0 +1,6 @@
+% header file
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\fancyhf{}
+\chead{Brain Imaging Data Structure v1.2.1 2019-08-14}
+\fancyfoot[LE,RO]{\thepage}

pdf_build_src/listings_setup.tex

@@ -0,0 +1,25 @@
+% Contents of listings-setup.tex
+\usepackage{xcolor}
+\usepackage{graphicx}
+
+\lstset{
+    basicstyle=\ttfamily,
+    numbers=left,
+    keywordstyle=\color[rgb]{0.13,0.29,0.53}\bfseries,
+    stringstyle=\color[rgb]{0.31,0.60,0.02},
+    commentstyle=\color[rgb]{0.56,0.35,0.01}\itshape,
+    numberstyle=\footnotesize,
+    stepnumber=1,
+    numbersep=5pt,
+    backgroundcolor=\color[RGB]{248,248,248},
+    showspaces=false,
+    showstringspaces=false,
+    showtabs=false,
+    tabsize=2,
+    captionpos=b,
+    breaklines=true,
+    breakautoindent=true,
+    escapeinside={\%*}{*)},
+    linewidth=\textwidth,
+    basewidth=0.5em
+}

pdf_build_src/pandoc_script.py

@@ -0,0 +1,43 @@
+"""Use the pandoc library as a final step to build the pdf.
+
+This is done once the duplicate src directory is processed.
+"""
+import os
+import subprocess
+
+
+def build_pdf(filename):
+    """Construct command with required pandoc flags and run using subprocess.
+
+    Parameters
+    ----------
+    filename : str
+        Name of the output file.
+
+    """
+    markdown_list = []
+    for root, dirs, files in os.walk('.'):
+        for file in files:
+            if file.endswith(".md") and file != 'index.md':
+                markdown_list.append(os.path.join(root, file))
+            elif file == 'index.md':
+                index_page = os.path.join(root, file)
+
+    default_pandoc_cmd = "pandoc "
+
+    # creates string of file paths in the order we'd like them to be appear
+    # ordering is taken care of by the inherent file naming
+    files_string = index_page + " " + " ".join(sorted(markdown_list))
+
+    flags = (" -f markdown_github --include-before-body cover.tex --toc "
+             "-V documentclass=report --listings -H listings_setup.tex "
+             "-H header.tex -V linkcolor:blue -V geometry:a4paper "
+             "-V geometry:margin=2cm --pdf-engine=xelatex -o ")
+    output_filename = filename
+
+    cmd = default_pandoc_cmd + files_string + flags + output_filename
+    subprocess.run(cmd.split())
+
+
+if __name__ == "__main__":
+    build_pdf('bids-spec.pdf')