Publishing and SharingPublishing and Sharing

Sherif FaragUniversity of North Carolina at Chapel Hill, USA

Publishing and SharingSpecific aim

• Documenting your code in a professional way and making it accessible for either the public or to a limited group.

Outline

• What is publishing ?– Dynamic vs Static– Uses of dynamic documentation– Examples of dynamic documentation

• What is Sharing ?– Importance of sharing source code– How to share your code– Revision control System– Examples of RCS

Publishing

• Creating a document that represent you research code in a professional way that is easy to follow and understand.

• Embedding code snippets into your document.

PublishingDynamic VS Static

Static Dynamic

PublishingDynamic VS Static in Typing

• int a; • a = 5; • cout << a + 5 ; • cout << b + 7 ;

• x = 23 • print x

C++, Java Python, R

( Good)

( Not Good)

PublishingDynamic VS Static Documentation

• A living document or dynamic document is a document that is continually edited and updated.

• A simple example of a living document is an article in Wikipedia, that permits anyone to freely edit its articles.

• A "dead" or "static" documents, such as an article in a single edition of the Encyclopaedia Britannica.

PublishingUses of Dynamic Documentation

• A nice and detailed way of reporting/documenting your research code.

• Makes editing of the document easier and efficient.

• Can be used on a regular basis by graduate students for delivering class assignments/ lab reports as well as professional writings such as a thesis or a manuscript.

PublishingExamples: Knitr

• Is an engine for dynamic report generation with R.

• It is a package in the statistical programming language R that enables integration of R code into LaTeX, LyX, HTML, Markdown Knitr

(R)

Latex

HTML

Markdown

Lyx

PublishingExamples: Latex

Before Building After Building

PublishingExamples: Latex

Before Building After Building

PublishingExamples: Knitr with Latex

Before Building After Building

PublishingExamples: Ipython Notebook

• IPython Notebook is a web-based interactive computational environment for creating IPython notebooks.

• An IPython notebook is a JSON document containing an ordered list of input/output cells which can contain code, text, mathematics, plots and rich media.

iPynb(Py)

Latex

HTML

MarkdownPDF

Python

PublishingExamples: IPython Notebook

Before Building After Building

Outline

• What is publishing ?– Dynamic vs Static– Uses of dynamic documentation– Examples of dynamic documentation

• What is Sharing ?– Importance of sharing source code– How to share your code– Revision control System– Examples of RCS

Sharing

Sharing

SharingImportance of Sharing Code

• Is a contributing factor to the maturation of people’s programming skills.

• Help optimizing current version of software by reducing number of bugs within a source code (Two brains better than one !!)

• Make programing more plannable and more efficient by splitting tasks between programmers.

• Pair programming: two programmers work as a pair together on one workstation. One, the driver, writes code while the other, the observer, pointer or navigator, reviews each line of code as it is typed in.

SharingHow to Share Your Code

• CD, DVD,SD, Flash drive, …,etc

• Cloud: Google drive, Dropbox, BOX, StackoverFlow, …,etc

• Revision Control System (RCS)

SharingRevision Control System (RCS)

• Is a software implementation of revision control that automates the storing, retrieval, logging, identification, and merging of revisions.

• RCS is useful for text that is revised frequently, for example programs, documentation, procedural graphics, papers, and form letters.

SharingExamples of RCS

SVN Git

Links

• Latex Tutorial: http://www.latex-tutorial.com/• Knitr: http://yihui.name/knitr/• Knitr examples: https://

github.com/yihui/knitr-examples• Ipython Notebook: http://

ipython.org/notebook.html• GIT: https://git-scm.com/• SVN: https://subversion.apache.org/