Creating Documentation in the CyVerse Learning Center¶
Goal¶
All users are invited to contribute to CyVerse documentation, from fixing a typo to contributing a new tutorial. This quickstart will get you through the initial steps of your contribution.
ReStructured Text Examples¶
Tip
Check the code (.rst) source to see how these examples are written in restructured text.
Writing your documentation using sample data¶
Where possible, you want write documentation instructions to be general enough for users can follow along with their own data. To help do this, you can use the sample data admonition to intersperse sample data-specific instructions into your generic instructions.
To do this, start your documentation with a description and where possible, a citation of the data:
Sample data
How to use provided sample data
In this guide, we will use an RNA-Seq dataset (“Zika infected hNPCs”). This experiment compared human neuroprogenetor cells (hNPCs) infected with the Zika virus to non-infected hNPCs. You can read more about the experimental conditions and methods here. Where appropriate, a note (in this orange colored background) in the instructions will indicate which options to select to make use of this provided dataset.
Sample data citation: Yi L, Pimentel H, Pachter L (2017) Zika infection of neural progenitor cells perturbs transcription in neurodevelopmental pathways. PLOS ONE 12(4): e0175744. 10.1371/journal.pone.0175744
Then, as you have instructions, intersperse the sample data .. admonition
First, enter the cutoff value for your dataset
Sample data
“Zika infected hNPCs” dataset:
Enter 30
Continue with next step…
Other admonitions¶
There are several admonitions you can use, but tip and warning are the most common for our documentation.
Tip
If you don’t see a desired species/genome contact us to have it added
Warning
When naming your samples and conditions, avoid spaces and special characters (e.g. !#$%^&/, etc.). Also be sure to be consistent with spelling.
Buttons and keyboard combinations¶
Where it adds clarity you can use this text to add buttons:
- Click Cancel to continue
- Press Control + P to print your result
URLs/Links¶
Have hyperlinks open in a new tab to avoid pushing the reader off the documentation page. Always use substitutions. Best practice is to define your substitutions in the cyverse_rst_defined_substitutions.txt file in this repo for easy future updating.
Bad link …
Good link …
Even better link (because it is defined in a separate file)
Images¶
Images should only be used when necessary.
Choose an image size that works for your page:
Better size:
Images should have a 1px black border:
Prerequisites¶
Downloads, access, and services¶
In order to complete this tutorial you will need access to the following services/software
Prerequisite Preparation/Notes Link/Download CyVerse account You will need a CyVerse account to complete this exercise CyVerse User Portal GitHub account You will need a GitHub account to complete this exercise GitHub A text editor You will need a text editor (word processing programs like Microsoft Word introduce formatting errors and are not acceptable). We recommend a free editor like Atom Atom
Platform(s)¶
We will use the following platform(s):
| Platform | Interface | Link | Platform Documentation |
|---|---|---|---|
| CyVerse Learning Center | Github repository and ReadTheDocs | CyVerse Learning Center | This document |
| GitHub | Online repository management | GitHub | GitHub Guide |
| Read the Docs | Online documentation platform | Read the Docs | Read the Docs Docs |
A. Improving Existing Documentation in the CyVerse Learning Center¶
All CyVerse documentation is a community effort. You can contribute in several ways including:
- Reporting typos or grammatical mistakes
- Identifying instructions that are out-of-date, unclear, or wrong
- Suggesting other improvements
You can help fix these by reporting a documentation issue. You can click
the 
icon on the lower-left of your screen and send us a message. Or,
if you are familiar with GitHub you can either file and issue or submit a
pull request. Creating issues just requires a few seconds of your time, so
we will cover that here:
Creating an issue on GitHub
At the bottom of the documentation there should be a link called Github Repo Link or Repo Link. Click this link to go to the GitHub Repository (the online location of the documentation text).
On the GitHub site, click the “Issues” tab near the top of the screen.
If the issue list is empty Click “New Issue”; You may need to login to your GitHub account. Give your issue a descriptive title and a comment. Once you are done, click “Submit new issue.” You will receive notifications (unless you opt out) from GitHub on the status of your issue.
If the issue list is contains issues If possible, check to see that the issue you identified is not in the current list. If your issue already exists, you may still wish to leave a comment. If you think your issue is new, click “New Issue”; you may need to login to your GitHub account. Give your issue a descriptive title and then leave a comment. Once you are done, click “Submit new issue.” You will receive notifications (unless you opt out) from GitHub on the status of your issue.
B. Creating New Documentation in the CyVerse Learning Center¶
These instructions assume some familiarity with GitHub. If you are not comfortable with GitHub, but have a documentation contribution to make, please email us with your ideas or content: Tutorials@CyVerse.org.
Tip
Every documentation piece is create from a template in a GitHub repository. There are some template-specific instructions in the README.md file in each repository. This Quickstart will highlight the main steps, but please refer to that readme file.
You will need to import a template repo into your own Github account. You can follow the Github instructions for importing a repo. The CyVerse template repos are:
After importing the template, clone it to your local computer and develop the text of your tutorial. See the README.md file in your downloaded template for specific step-by-step instructions. CyVerse documentation is written in ReStructured Text, a plain text format very similar to Markdown. See the ReStructured Text examples on the next page.
Once your materials are complete, please notify Tutorials@CyVerse.org 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. If your documentation contains example data, we will also assist you in making sure that data is accessible to others who would use the documentation.
Tutorial Creation Flowchart
Tip
You can use these templates and instructions to create your documentation without having it hosted on the CyVerse Learning Center. See the Read the Docs Docs.
Additional information, help¶
Post your question to the user forum: Ask CyVerse
Fix or improve this documentation
- Search for an answer: CyVerse Learning Center
- Ask us for help:
click on the lower right-hand side of the page
- Report an issue or submit a change: Github Repo Link
- Send feedback: Tutorials@CyVerse.org