generalised, tested and documented

README.md

@@ -1,16 +1,68 @@
-# pyatomica
-A package for analysis of atomic/electonic level data
+# ipypublish
+A workflow for creating/editing publication ready scientific reports from one or more Jupyter Notebooks, without leaving the browser!
 
-## Metadata
+![WorkFlow Example](/example_workflow.gif)
+
+See ![notebooks/Example.ipynb](converted/Example.pdf) and ![converted/Example.pdf](converted/Example.pdf) for an example of the potential input/output.
+
+## Workflow
+
+1. Create a notebook with some content!
+2. optionaly create a .bib file and logo image
+3. Adjust the notebook and cell metadata. The default latex template (latex_hide_input_output.tplx) outputs all raw/markdown cells (unless tagged latex_ignore), and then only output cells with figure, table or equation tags.
+4. Run the run_nbconvert.sh script for either the specific notebook, or a folder containing multiple notebooks. 
+5. A converted folder will be created, into which final .tex .pdf and _viewpdf.html files will be output, named by the notebook or folder input
+
+## Setup
+
+Using [Conda](https://conda.io/docs/) is recommended:
+
+	conda create --name ipyreport -c conda-forge jupyter
+
+For helpful tools in the notebook (like toc sidebar):
+
+	conda install --name ipyreport jupyter_contrib_nbextensions
+
+For a more extensive setup of useful packages:
+
+	conda create --name ipyreport -c conda-forge -c matsci --file conda_packages.txt
+
+## run_nbconvert script
+
+To see all options for this script:
+
+	./run_nbconvert.sh -h
+
+For example, to convert the Example.ipynb notebook:
+
+	./run_nbconvert.sh -b bibliographies/example.bib -l logos/logo_example.png notebooks/Example.ipynb
+
+If a folder is input, then the .ipynb files it contains are processed and combined in 'natural' sorted order, i.e. 2_name.ipynb before 10_name.ipynb
+
+## Metadata Tags
 
 For titlepage, enter in notebook metadata:
 
-	"latex_metadata": {
-	  "title": "Article Name",
-	  "subtitle": 
-	},
+  "latex_metadata": {
+    "author": "Authors Name",
+    "email": "[email protected]",
+    "supervisors": [
+      "First Supervisor",
+      "Second Supervisor"
+    ],
+    "title": "Main-Title",
+    "subtitle": "Sub-Title",
+    "tagline": "A tagline for the report.",
+    "institution": [
+      "Institution1",
+      "Institution2"
+    ],
+    "logo": "logo_example"
+  },
 
-all keys are optional
+- all keys are optional
+- if there is no title, then the notebook filename will be used
+- if run_nbconvert.sh is called on a folder, then the meta data from the first notebook will be used
 
 To ignore a markdown cell:
 
@@ -21,17 +73,24 @@ For figures, enter in cell metadata:
 	  "latex_figure": {
 	    "caption": "Figure caption.",
 	    "label": "fig:flabel",
+	    "placement": "H"
 	    "widefigure": false
 	  }
 
+- `placement` is optional and constitutes using a placement arguments for the figure (e.g. \begin{figure}[H]). See https://www.sharelatex.com/learn/Positioning_images_and_tables.
+- `widefigure` is optional and constitutes expanding the figure to the page width (i.e. \begin{figure*}) (placement arguments will then be ignored)
+
 For tables, enter in cell metadata:
 
 	  "latex_table": {
 	    "caption": "Table caption.",
 	    "label": "tbl:tlabel"
+	    "placement": "H"
 	  }
 
-For tables, enter in cell metadata:
+- `placement` is optional and constitutes using a placement arguments for the table (e.g. \begin{table}[H]). See https://www.sharelatex.com/learn/Positioning_images_and_tables.
+
+For equations, enter in cell metadata:
 
 	  "latex_equation": {
 	    "label": "eqn:elabel"
@@ -41,11 +100,85 @@ label is optional
 
 ## Citations
 
-Using https://github.com/retorquere/zotero-better-bibtex/releases/tag/1.6.100 for drag and drop cite keys \cite{kirkeminde_thermodynamic_2012}
+Using Zotero's Firefox plugin and https://github.com/retorquere/zotero-better-bibtex/releases/tag/1.6.100 for;
+
+- automated .bib file updating 
+- drag and drop cite keys \cite{kirkeminde_thermodynamic_2012}
 
 Can use: 
 
 	<cite data-cite="kirkeminde_thermodynamic_2012">(Kirkeminde, 2012)</cite> 
 
 to make it look better in html, but not specifically available for drag and drop in Zotero 
 
+## Notebook code for improved latex/pdf output
+
+	%matplotlib inline
+	%config InlineBackend.figure_format = 'svg'
+	import matplotlib as mpl
+	mpl.rcParams['figure.figsize'] = (5.0, 2.5)
+	import matplotlib.pyplot as plt
+
+	import pandas as pd
+	import numpy as np
+	pd.set_option('display.latex.repr',True)
+	pd.set_option('display.latex.longtable',False)
+	pd.set_option('display.latex.escape',False)
+	import sympy
+	sympy.init_printing(use_latex=True)
+
+	from IPython.display import Image, Latex
+
+	from PIL import Image as PImage
+	def read_images(paths):
+	    return [PImage.open(i).convert("RGBA") for i in paths]
+	def images_hconcat(images, width=700,height=700, 
+	                   gap=0,aspaths=True):
+		""" concatenate multiple images horizontally """
+	    images = read_images(images) if aspaths else images
+	    widths, heights = zip(*(i.size for i in images))
+	    total_width = sum(widths) + gap*len(images)
+	    max_height = max(heights)
+	    new_im = PImage.new('RGBA', (total_width, max_height))
+	    x_offset = 0
+	    for im in images:
+	        new_im.paste(im, (x_offset,0),mask=im)
+	        x_offset += im.size[0] + gap
+	    new_im.thumbnail((width,height), PImage.ANTIALIAS)
+	    return new_im
+	def images_vconcat(images, width=700,height=700, 
+	                   gap=0, aspaths=True):
+		""" concatenate multiple images vertically """
+	    images = read_images(images) if aspaths else images
+	    widths, heights = zip(*(i.size for i in images))
+	    max_width = max(widths)
+	    total_height = sum(heights) + gap*len(images)
+	    new_im = PImage.new('RGBA', (max_width, total_height))
+	    y_offset = 0
+	    for im in images:
+	        new_im.paste(im, (0,y_offset),mask=im)
+	        y_offset += im.size[1] + gap
+	    new_im.thumbnail((width,height), PImage.ANTIALIAS)
+	    return new_im
+	def images_gridconcat(pathslist,width=700,height=700,
+	                     aspaths=True,hgap=0,vgap=0):
+		""" concatenate multiple images in a grid 
+		
+		pathslist : list of lists
+		"""
+	    himages = [images_hconcat(paths,gap=hgap,aspaths=aspaths) for paths in pathslist]
+	    new_im = images_vconcat(himages,gap=vgap,aspaths=False)
+	    new_im.thumbnail((width,height), PImage.ANTIALIAS)
+	    return new_im
+
+## Miscellaneous
+
+I also use the Firefox Split Pannel extension to view the {name}_viewpdf.html page and monitor changes to the pdf.
+
+## Acknowledgements
+
+I took strong influence from:
+
+- http://blog.juliusschulz.de/blog/ultimate-ipython-notebook#cite2c
+- https://livingthing.danmackinlay.name/jupyter.html
+- Notebook concatination adapted from https://github.com/jupyter/nbconvert/issues/253

converted/Example_viewpdf.html

@@ -0,0 +1,55 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"  
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+
+<head>
+    <meta http-equiv="content-type" content="text/html; charset=windows-1252">
+    <title>View PDF</title>
+
+    <script type="text/javascript">
+ 	   var filepath = "Example.pdf";
+       var timer = null;
+
+       function refresh(){
+          var d = document.getElementById("pdf"); // gets pdf-div
+          d.innerHTML = '<iframe style="position: absolute; height: 100%; border: none" id="ipdf" src='+window.filepath+'  width="100%"></iframe>';
+       }
+
+       function autoRefresh(){
+          timer = setTimeout("autoRefresh()", 20000);
+          refresh();
+       }
+
+       function manualRefresh(){
+          clearTimeout(timer); 
+          refresh();   
+       }
+	   function check_pdf() {
+	     var newfile = document.f.userFile.value;
+	     ext = newfile.substring(newfile.length-3,newfile.length);
+	     ext = ext.toLowerCase();
+	     if(ext != 'pdf') {
+	       alert('You selected a .'+ext+
+	             ' file; please select a .pdf file instead!'+filepath);
+	       return false; }
+	     else
+			 alert(newfile);
+		     window.filepath = newfile;
+			 alert(filepath);
+			 refresh();
+	       return true; }
+    </script>
+
+</head>
+<body>
+	<!-- <form name=f onsubmit="return check_pdf();"
+	    action='' method='POST' enctype='multipart/form-data'>
+	    <input type='submit' name='upload_btn' value='upload'>
+		<input type='file' name='userFile' accept="application/pdf">
+	</form> -->
+	<button onclick="manualRefresh()">manual refresh</button>
+   <button onclick="autoRefresh()">auto refresh</button>
+   <div id="pdf"></div>
+</body> 
+<script type="text/javascript">refresh();</script>
+</html>