example_directives_delete.rst

|CyVerse_logo|_

|Home_Icon|_ Learning Center Home

STYLE TIPS - DELETE THIS PAGE BEFORE PUBLISHING

Tip

Check the code (.rst) source to see how these examples are written in restructured text.

Many of the examples 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

1. First, enter the cutoff value for your dataset

   Sample data

   "Zika infected hNPCs" dataset:

   Enter 30

2. Continue with next step...

Using in-line questions with tips

Sometimes you may want to ask in-line questions.

Question

How do you get to Carnegie Hall?

Answer

Practice, practice, practice

You can hide long sections of text...

Expand to read more

Open a connection to a public folder

1. Open CyberDuck
2. If the browser is not already open, select File - New Browser

3. Create a new connection by clicking on the + in the lower right

   (next to the pencil and minus sign)

4. In the top dropdown menu, select iPlant Data Store

5. In the dialog box, name your connection something relevant, like the name

   of the folder you want to browse to

6. Enter your user name in the appropriate field. If you are connecting to

   public folder, you can also enter anonymous in this field

7. In the Path field, enter /iplant/home/shared, or some subdirectory.

8. Close the dialog window. Now, in your list of connections, you should see

   a new connection with the name you chose. Click on that, and you should go

   directly to the public folder.

Other admonitions

There are several admonitions you can use, but tip and warning are the most common for our documentation.

learning-objectives

• Objective 1
• Objective 2
• Objective 3

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:

1. Click :guilabel:`&Cancel` to continue
2. Press :guilabel:`&Control` + :guilabel:`&P` to print your result
3. Fix the |CyVerse_launch| link in custom_url.txt to use this button to launch a quicklaunch link in the DE (the embed HTML the DE generates may not render properly in RTD)

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 ...

bad google

Good link ...

Google

Even better link (because it is defined in a separate file)

|CyVerse User Portal|

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: