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
|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|
|/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.
- Send an email to Tutorials@CyVerse.org
More complex contributions
Fixing and/or improving documentation via GitHub
- Fork this repo to your GitHub account
- 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).
- Commit change; if working from a local copy, push those changes to your fork in Github.
- Submit a pull request back to the master repository; you may need to act on feedback before your request is merged.
(This section to be removed)
Edit the index.rst. Save images or other files in the appropriate directories. See our recommended style guide for writing documentation below.
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.
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'
Edit the 'conf.py' file to set the project and author information
Build the tutorial:
$ make html
Your HTML site will be in the _build directory that has been created (you can preview this in your web browser at this time).
Commit your changes and push the tutorial back to GitHub.
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
- 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/####"
|Steps generally begin with a verb or preposition||
|Locations of files are given in absolute paths||
|Top-level menus in Discovery Environment Apps in double quotes||
|Subheadings/steps in Discovery Environment Apps in single quotes||
|Buttons and keywords in bold||