Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
buildenv
img
misc
slides
.gitignore
Contributors_maintainers.md
License.md
Makefile
README.md
conf.py
cyverse_rst_defined_substitutions.txt
index.rst
make.bat
requirements.txt
step1.rst
step2.rst
step3.rst
step4.rst
step5.rst

README.md

CyVerse Data Commons DOI Request Quickstart Repo

You should import this repo to build CyVerse Quickstarts

See this quickstart rendered on ReadTheDocs

What this repo contains

Item Description Notes
index.rst Home page for documentation. Before you being. documents written in markdown will need to be converted to restructured text
step2.rst Organize the dataset in the CyVerse Data Store
step3.rst Add metadata to the dataset top folder
step4.rst Submit the request for the DOI and wait for validation
step5.rst After data are published
/img (folder) Images for the tutorials CyVerse logos and other useful images are already here
example_directives_delete.rst Example page with code for common restructured text objects
cyverse_rst_defined_substitutions.txt restructured text substitutions for common URLs and images
conf.py Place to add tutorial and author name;versioning
README.md This page
/slides (folder) Slides associated with the 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

More complex contributions

Fixing and/or improving documentation via GitHub

  1. Fork 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 the repo to work on your local computer. For very significant changes (we suggest making a new branch).
  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.

Procedure

(This section to be removed)

  1. Edit the index.rst. Save images or other files in the appropriate directories. See our recommended style guide for writing documentation below.

  2. Since tutorials will likely span multiple pages, you can copy internal pages 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.

  3. Save your work:

    • individual pages (e.g. 'index.rst, step2.rst')
    • images (as '.png' files in the the 'img' folder)
    • changes or additions to 'cyverse_rst_defined_substitutions.txt'
  4. Edit the 'conf.py' file to set the project and author information

  5. Build the tutorial:

     $ make html
    
  6. Your HTML site will be in the _build directory that has been created (you can preview this in your web browser at this time).

  7. Commit your changes and push the tutorial back to GitHub.

  8. 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. 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. 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
  • Use the 'raw ::html' directive to enter hyperlinks so that they will open in a new tab. See each repo for an example of the code
  • Example data associated with documentation should be anonymously available on CyVerse Data Commons (Tutorials@cyverse.org 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
  • Click on the button
  • Under the "Result" menu
Locations of files are given in absolute paths
  • /dir1/dir2/file.extension
Top-level menus in Discovery Environment Apps in double quotes
  • Under "Input" select...
Subheadings/steps in Discovery Environment Apps in single quotes
  • For 'sensitivity' enter...
Buttons and keywords in bold
  • Click on Apps
  • Select Arabidopsis
  • Set 'sensitivity' to Medium
You can’t perform that action at this time.