Making Tutorials¶

This project was supported by grants from the National Institute of Biomedical Imaging and Bioengineering (U24EB029012) from the National Institutes of Health.

Authors:Jess Tate

Overview¶

This tutorial demonstrates how to use markdown to create new tutorials for UncertainSCI. It will walk through all the files needed and the basic structure needed expected for tutorials. Knowledge of Markdown, Github, Python, Sphinx, and Read the Docs will be useful. If you have questions, please ask.

Software requirements¶

UncertainSCI¶

To make a Tutorial for UncertainSCI, start with an up-to-date version of the code and documentation. Download the source code or clone the repository from github. We suggest creating a fork of the repository so that you can track your changes and create pull requests to the UncertainSCI repository. UncertainSCI requirements are found here

Dependencies and Development Tools¶

UncertainSCI uses Read the Docs and Sphinx to build and host tutorial documentation. This platform converts markdown files to html for web viewing using Sphinx, a Python Library. Testing the new documentation may require building the web pages locally for viewing. This will require installing Python, pip, Sphinx, Recommonmark, and other packages in the docs/requirements.txt file. More information can be found in the walkthorugh and on the Sphinx documentation.

Creating Your UncertainSCI Fork¶

With your own github account, go to the UncertainSCI Github page. Click the fork button on the upper right side of the page. It will ask you where to move the fork to, chose your own account. Once the repository is forked, clone it to your local machine with the following command.

$git clone https://github.com/[yourgithubaccount]/UncertainSCI.git

After the the code is cloned, navigate to the repository directory and add the upstream path to the original UncertainSCI repository.

$git remote add upstream https://github.com/SCIInstitute/UncertainSCI.git

You should be able to see both your and the original repositories when you use the command:

$git remote -v

The fork is good to go, but you will need to sync the fork occasionally to keep up with the changes in the main repository. To sync your fork, use the following commands:

$git fetch upstream

$git checkout master

$git merge upstream/master

You should sync and merge your fork before you start a new module and before you create a pull request.It is a good practice to create a new branch in your fork for every module you will be adding. The command to create a new branch is:

$git checkout -b [branch_name]

Please see the Github help page for more information.

Files Needed for a New Tutorial¶

This chapter will describe the files need to create a Tutorial for UncertainSCI.

Overview of Files Needed for a Tutorial¶

To make a new tutorial, a markdown file is required for the content of the tutorial. Other files, such as images, may also be included. In addition to the new files for the tutorial, a link to the new tutorial should be added to the User Documents file.

Markdown File¶

The main file needed for a new tutorial is a markdown file. The file should have an file ending of .md and should be located in the UncertainSCI/docs/tutorials/ directory. There is a template file that can be used, or an existing tutorial like this one can be used.

If using math equations in a latex, a call to the mathjax server is required at the begining of the document:

<script type="text/javascript" async
  src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_CHTML">
</script>

Sphinx will build the menu and table of contents from the header names, and the document will be formated correctly if the proper markdown headings levels are used. For instance, the Document title should be the first content:

# Title

Then the chaper headings:

## Overview
## Chapter The First
## ETC.

An important part of the document is to acknowledge the authors and funding sources. Include text similar to this after the document title:

This project was supported by grants from the National Institute of Biomedical Imaging and Bioengineering (U24EB029012) from the National Institutes of Health.

Authors:  
Smart people here

Chapters and sections will appear in the table of contents with the page titles. Once the file is added to the docs/tutorial/index.rst file

Added Figures¶

Most tutorials require a number of screenshots and other images. Figures and images should be added in a folder for each tutorial in the UncertainSCI/docs/user_docs/ folder. The figure folder should be named after the tutorial, for example, the images in this tutorial are in a folder called HowToTutorial_figures. Instructions on how to use the images and figures are found here

Additional Files¶

Additional files added to the tutorials folder should be minimized as much as possible. Example scripts should be located in the UncertainSCI/examples directory and example data will, generally, need separate hosting. However, if one or two files are needed, they may be added to the UncertainSCI/docs/tutorials/ with a consistent naming scheme. Bibtex file with a matching name should be added in UncertainSCI/docs/tutorials/, yet if multiple additional files are needed, they should placed in a new folder indicating the tutorial: UncertainSCI/docs/tutorials/[tutorial name]_files.

Linking to New Tutorial¶

For the new tutorial to be visible on the tutorials page, add the filename to the list in the UncertainSCI/docs/tutorials/index.rst file.

Testing Documentation¶

This chapter describes how to test the look and content of the new tutorial. Test the generated github-pages with either a local Sphinx build or using the online build on Read the Docs.

Testing Locally¶

Testing the documentation locally involves building documentation website on your local machine using Sphinx and Recommonmark. These instructions are adapted from Read the Docs’ help page.

Installing Shpinx¶

To install the Sphinx, make sure that a relatively recent version of Python 3. Installing sphinx and other dependencies is easiest with pip, just run

pip install -r requirements.txt

in the UncertainSCI/docs folder and the relavent python dependencies, including Sphinx, will be installed.

Alternatively, the dependencies listed in UncertainSCI/docs/requirements.txt file could be installed seperately.

Please ask if you have any questions.

Building Documentation¶

Once the relavent python packages are installed properly, such as with pip, building the documentation pages is as simple as running

make html

in the UncertainSCI/docs folder. A script will run and, assuming no errors, the html pages will be generated within the UncertainSCI/docs/_build/ folder. Any of the html files can be tested by opening it in a browser.

Testing Online¶

In addition to building and testing the documentation pages locally, they can also be tested online with Read the Docs. Any branch of a github repo can be built one the Read the Docs page. Online builds can only be triggered deirectly on the readthe docs by those who have access. However, every pull request to the UncertainSCI repo will trigger an online build that can be viewed by anyone. Pull request autobuild Documentation autobuild on a Github Pull Request The documentation page can be viewd by clicking on the details link, shown in the image. Pull requests are required when submitting contributions to UncertainSCI.

Please ask if you have any questions.

Adding Content¶

This chapter provides some examples of how to add some types of content that may be needed for a tutorial. For general Markdown info, see here and here.

Figures¶

Figures can be added fairly easily in Markdown, with a simple call to the location:

![Alt text](../_static/UncertainSCI.png "Title")

example markdown UncertainSCI example image

However, using a bit of html allows us to reference the figure easier:

<figure id="example">
<img src="../_static/UncertainSCI.png" alt="UncertainSCI example image">
<figcaption>Example for including an image in tutorial.</figcaption>
</figure>

And to reference (not working with Sphinx):

<a href="#example">reference the figure</a>

UncertainSCI example image — Example for including an image in tutorial.

Math¶

Math equations can be used in Markdown using MathJax. Mathjax will convert LaTex format:

$$ \frac{\partial \rho}{\partial t} + \nabla \cdot \vec{j} = 0 \,. \label{eq:continuity} $$

$$ \frac{\partial \rho}{\partial t} + \nabla \cdot \vec{j} = 0 ,. \label{eq:continuity} $$ It can also use MathJax specific tags:

\\[ x = {-b \pm \sqrt{b^2-4ac} \over 2a} \\]

\[ x = {-b \pm \sqrt{b^2-4ac} \over 2a} \]

Citations¶

Citations in Markdown uses Pandoc. The citations can stored in Bibtex format

TODO.

Snippets¶

Links¶

Including links in Markdown is simple, just use <> or [](). For example, an internal link for section Adding Content is :

[Adding Content](#adding-content)

When using internal links to sections, include the name of the section, all lower case and with - replacing spaces, and all special characters ommited. Linking to other pages in within the UncertainSCI documentation requires a relative path. Demos is:

[Demos](../tutorials/demos.html#demos)

Links to other websites can include the full URL. Using <> will show the URL, []() will hide it with other text.

<https://www.markdownguide.org>
[Markdown](https://www.markdownguide.org)

https://www.markdownguide.org Markdown

Referencing Sphynx¶

TODO

To link the UncertainSCI API generated using Sphynx, Use this syntax: [text](../api_docs/pce.html#polynomial-chaos-expansions).