first commit

Contributors_maintainers.md

@@ -0,0 +1,12 @@
+#Contributors and Maintainers
+
+## CyVerse Maintainer: 
+
+**Name:**
+**Email:**
+
+## We would like to thank the following contributors
+
+|Name|Contact Info|Institution|Notes|
+|----|------------|-----------|-----|
+|||||

License.md

@@ -0,0 +1,21 @@
+# License for CyVerse Documentation
+
+Documentation contained in this repo is made available under at CC BY 4.0 License: https://creativecommons.org/licenses/by/4.0/legalcode 
+
+You may:
+
+- Share—copy and redistribute the material in any medium or format
+- Adapt—remix, transform, and build upon the material
+
+for any purpose, even commercially. The licensor cannot revoke these freedoms as long as you follow these license terms:
+
+**Attribution—** You must give appropriate credit (mentioning that your work is derived from work that is Copyright (c) CyVerse and, where practical, linking to http://www.cyverse.org/), provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+No additional restrictions—You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. With the understanding that:
+
+- You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+- No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
+
+This license is superseded by and subject to any and all other polices of CyVerse as described at: http://www.cyverse.org/policies; CyVerse is based upon work supported by the National Science Foundation under Grant No. DBI-0735191 and DBI-1265383.
+
+Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Makefile

@@ -0,0 +1,192 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/ReadtheDocsBuild.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsBuild.qhc"
+
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/ReadtheDocsBuild"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsBuild"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

README.md

@@ -0,0 +1,123 @@
+# Template CyVerse Tutorial Repo
+
+You should import this repo to build CyVerse Tutorials
+
+## How CyVerse Learning Center documentation is built
+
+Each CyVerse Tutorial or Quickstart has its own [ReadtheDocs](https://readthedocs.org/) page which in turn is built from its own repo (See the template repos at [https://github.com/CyVerse-learning-materials](https://github.com/CyVerse-learning-materials)). Starting from a [ResStructured text file](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html) (index.rst) The documentation is built using [Sphinx](http://www.sphinx-doc.org/en/1.4.8/), and hosted on a repo configured with GitHub [Webhooks/Services](http://docs.readthedocs.io/en/latest/webhooks.html). Finally, the site is added to ReadtheDocs. Directions for completing this workflow are below **(See Building a Tutorial from Scratch)**.
+
+## Documentation types
+
+- **Tutorials:** Tutorials teach. Users should be able to follow an example dataset through the steps of a tutorial and gain understanding about what is happening along those steps. These are in-depth guides that usually address a scientific question by covering the major steps of a scientific workflow. A tutorial is ‘successful’ when a user is able to follow the tutorial a second time with their own data and obtain reasonable results.
+- **Quick Starts:** These materials are short tutorials that cover the minimal amount of information needed to complete an **operational task** (e.g. uploading data, reformatting a file, etc. ); there is no significant explanation of the science or interpretation of results. QSs highlight available resources, answer common questions (derived from user forum), and refer users to the most appropriate materials.
+
+**Examples:**
+
+- Uploading a file: Quick Start
+- Cleaning FastQ reads: Quick Start
+- Uploading files to SRA: Could be both
+- Assembling a transcriptome: Tutorial
+
+
+## What this repo contains
+
+|Item|Description|Notes|
+|----|-----------|-----|
+|tutorial_template.md|Edit this template to create a tutorial|documents written in markdown will need to be covered to restructured text|
+|tutorial_template.md|This is a barebones markdown template|documents written in markdown will need to be covered to restructured text|
+|/img (folder)|Place images for your tutorials here|CyVerse logos and other useful images are already here| 
+|/slides (folder)|Place slides associated with your tutorial here|version controlled files preferred, PPT acceptable|
+|/misc (folder)|miscellaneous needed for building documentation| |
+|License.md|License|this license file applies to all materials created by CyVerse for this documentation|
+|Contributors_maintainers.md|Contact information and recognition||
+
+
+## Simple contribution instructions
+
+### Reporting an error or issue via GitHub
+
+- Click the 'issues' tab at the top of this GitHub page to let us know about a simple mistake such as a typo or missing file. 
+
+ OR
+
+- Send an email to [[email protected]](mailto:[email protected])
+
+## More complex contributions
+
+### Fixing and/or improving documentation via GitHub
+
+1. [Fork](https://help.github.com/articles/fork-a-repo/) this repo to your GitHub account
+2. Make edits directly to the **index.rst** file. Edits may be made to the fork the web interface to your GitHub account or [clone](https://help.github.com/articles/cloning-a-repository/) the repo to work on your local computer. For very significant changes (we suggest [making a new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/)). 
+3. Commit change; if working from a local copy, push those changes to your fork in Github. 
+4. Submit a pull request back to the master repository; you may need to act on feedback before your request is merged. 
+
+
+## Building a Tutorial from Scratch
+
+If you want to go beyond just creating a markdown file, you will need to install some software. 
+
+**You will need the following software**
+
+1. Python (2.7.9 or later) - This is required for the Sphinx package that will build our documentation:
+    - https://www.python.org/downloads/
+2. If needed, install pip: 
+    - https://packaging.python.org/installing/#install-pip-setuptools-and-wheel
+3. Sphinx - This will build our tutorials into HTML and other formats (this uses the Python package installer 'pip' so Python must be installed first); we will also install the theme we need for our documentation
+
+        $ pip install sphinx sphinx-autobuild sphinx_rtd_theme
+4. RestView - Optional, but makes it easy to preview ReStructured text files [http://rst.ninjs.org/](http://rst.ninjs.org/) or install:
+
+        $ pip install restview 
+5. git - We use git to version control our documentation and manage with GitHub
+    - https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+
+**Note:** For your convenience, a markdown version of the template is provided. We'd appreciate if you convert it to ReStructured text, but since the conversion is not perfect, let us know if you need help and we will assist you with the process. 
+
+
+**You will need the following accounts**
+
+1. GitHub account - Will make it possible to collaborate on the documentation:
+    - https://github.com/
+
+
+### Procedure 
+
+1. **Import** (not clone) the CyVerse base tutorial repo following GitHub's directions here: https://help.github.com/articles/importing-a-repository-with-github-importer/
+    - The CyVerse template tutorial repo URL is **https://github.com/CyVerse-learning-materials/cyverse_tutorial_template**
+    - Name your repo for the name of your quickstart or tutorial, e.g. *'name_tutorial'*
+2. Edit the **index.rst**. Save images or other files in the appropriate directories. **See our recommended style guide for writing documentation below.**
+3. Since tutorials will likely span multiple pages, you can copy the 'step1.rst' page as many times as needed. Update the table of contents at the top of the 'index.rst' accordingly. We will have **only one tutorial or quick start per repo.**
+4. Save your work as  *'index.rst'*
+5. Edit the *'conf.py'* file to set the project and author information
+6. Build the tutorial:
+
+        $ make html
+7. Your HTML site will be in the _build directory that has been created (you can preview this in your web browser at this time).
+8. Commit your changes and push the tutorial back to GitHub.
+9. Notify [[email protected]](mailto:[email protected]) that your tutorial is ready for inclusion in the main CyVerse documentation repo. We will review and verify the contribution, and add you as a maintainer repo in the CyVerse collection. You should make future edits following the instructions above for 'Fixing and/or improving documentation via GitHub.' Alternatively, you can host your tutorial independently on ReadTheDocs following their [instructions for importing documentation](https://docs.readthedocs.io/en/latest/getting_started.html#import-your-docs). We will also follow up about ensuring test data associated with the documentation are available and open. 
+
+
+### Documentation Style Guide
+
+*General Principles*
+
+- Write instructions in short numbered steps. 
+- Where possible limit step to one action; small final actions such as 'press submit' should be separated by a semicolon
+- Limit the use of screenshots; where they are needed, use ReStructured text directives for [substitution of images](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions) and label them in numbered order in the text (e.g. |image1|)
+- Example data associated with documentation should be anonymously available on CyVerse Data Commons ([email protected] can help you with this)
+- Discovery Environment applications should be directly linked to documentation (clicking the 'info' button on any application will give you the 'App URL')
+- Atmosphere images should be directly linked to documentation (e.g. "atmo.cyverse.org/application/images/####". 
+
+*Specific examples*
+
+|Instruction|Example|
+|-----------|-------|
+|Steps generally begin with a verb or preposition|<ul><li>Click on the button<li>Under the "Result" menu</ul>|
+|Locations of files are given in absolute paths|<ul><li>/dir1/dir2/file.extension</ul>|
+|Top-level menus in Discovery Environment Apps in double quotes|<ul><li>Under "Input" select...</ul>|
+|Subheadings/steps in Discovery Environment Apps in single quotes|<ul><li>For 'sensitivity' enter...</ul>|
+|Buttons and keywords in bold|<ul><li>Click on **Apps**<li>Select **Arabidopsis**<li>Set 'sensitivity' to **Medium**</ul>|
+
+
+
+

conf.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# General information about the project.
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(__file__))
+
+from misc.cyverse_sphinx_conf import *  # noqa
+
+project = 'YOUR PROJECT NAME HERE as topic_tutorial'
+copyright = '2016, CyVerse'
+author = 'your_name'
+version = '1.0'
+release = '1.0'
+
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright