diff --git a/Admin_scripts/README.md b/Admin_scripts/README.md index bf55463..0357fba 100644 --- a/Admin_scripts/README.md +++ b/Admin_scripts/README.md @@ -1,6 +1,6 @@ # Pathogen Informatics Training - Admin scripts -This directory contains a number of scripts that can be used to convert Jupyter Notebooks to PDF. Before merging a notebook into the sanger-pathogens fork, please make sure that it conforms to the styleguide in `Guide_for_developers` and that you can do a successful conversion of the notebook with the admin scripts. +This directory contains a number of scripts that can be used to convert Jupyter Notebooks to PDF. Before merging a notebook into the sanger-pathogens fork, please make sure that it conforms to the style guide in `Guide_for_developers` and that you can do a successful conversion of the notebook with the admin scripts. ## Usage Make sure that your version of MacTeX (in particular lualatex) is up to date. @@ -12,4 +12,7 @@ In the notebook directory that you wish to convert, run: Edit the .tex that was generated so that it looks ok (for instance by adding page breaks, checking that text wrapping in command blocks don't exceed page width, and fixing image positions). Then run `lualatex` to convert the file to PDF. ## Dependencies -- [MacTeX](https://tug.org/mactex/) or similar \ No newline at end of file +- [MacTeX](https://tug.org/mactex/) or similar + +## Hints +* If an image wraps over a new page, it can cause blank spaces and unusual formatting. To get around it, put a /newpage line in the .tex file before the image. \ No newline at end of file diff --git a/Guide_for_developers/styleguide.md b/Guide_for_developers/styleguide.md index 3ab718a..5882c28 100644 --- a/Guide_for_developers/styleguide.md +++ b/Guide_for_developers/styleguide.md @@ -1,4 +1,4 @@ -# Styleguide for Pathogen Informatics Training Notebooks +# Style guide for Pathogen Informatics Training Notebooks This document contains some guidelines for creating a new Pathogen Informatics Training Notebook. * Included in the directory is a template for the index page. When starting on a new notebook, create a directory in pathogen-informatics-training/Notebooks and make a copy of template.ipynb. @@ -10,11 +10,14 @@ This document contains some guidelines for creating a new Pathogen Informatics T `jupyter notebook index.ipynb` * Below are some general guidelines for the layout of the new notebook: -** With the exception of scripts, put commands in separate boxes, not together. -** When using minus signs for equations, make sure to use the real minus sign and not the hyphen. -** Make sure images are in their own box, and refer to them as ![title](path/from/notebookdir). Give the image a short but decsriptive title, as this will show up in the pdf. -** At the end of each page, please include a link to the previous page, the next page and the index page. On the index page and the final page, also include a link to the answer sheet. -** Create one answer sheet for the entire tutorial and divide the answers into the tutorial sections. Add a table of contents at the top of the page (see RNA-Seq tutorial) -** Please make sure that all commands executed in the tutorial work properly. -** Also make sure that the notebook can be converted to pdf using the admin scripts as described in pathogen-informatics-training/Admin_scripts/README.md. Include the final pdf and the tex file in the final commit. + - With the exception of scripts, put commands in separate boxes, not together. + - When using minus signs for equations, make sure to use the real minus sign and not the hyphen. + - Make sure images are in their own box, and refer to them as: + + `![title](path/from/notebookdir)` + - Give the image a short but decsriptive title, as this will show up in the pdf. + - At the end of each page, please include a link to the previous page, the next page and the index page. On the index page and the final page, also include a link to the answer sheet. + - Create one answer sheet for the entire tutorial and divide the answers into the tutorial sections. Add a table of contents at the top of the page (see RNA-Seq tutorial) + - Please make sure that all commands executed in the tutorial work properly. + - Also make sure that the notebook can be converted to pdf using the admin scripts as described in pathogen-informatics-training/Admin_scripts/README.md. Include the final pdf and the tex file in the final commit.