This is a template for a Sphinx/readthedocs-style (https://readthedocs.com/)lesson template for the Genomics Education Alliance https://qubeshub.org/community/groups/gea.
You should import this repo to build a GEA lesson
Starting from a ResStructured text file (index.rst) The documentation is built using Sphinx, and hosted on a repo configured with GitHub Webhooks/Services. Finally, the site is added to ReadtheDocs. Directions for completing this workflow are below (See Building a Tutorial from Scratch).
| Item | Description | Notes |
|---|---|---|
| index.rst | Edit this template to create your documentation | documents written in markdown will need to be converted to restructured text |
| section1.rst | If documentation has more than one page, use this for the second through second-to-last page; copy as needed | copy as needed for additional pages 1..(n-1) |
| section2.rst | If documentation has more than one page, this should always be the last page | |
| /img (folder) | Place images for your lessons here | logos and other useful images are already here |
| /assets (folder) | Place slides, handouts, etc. associated with your lesson 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 GEA for this lesson |
| Contributors_maintainers.md | Contact information and recognition |
- 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]
- 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.
If you want to go beyond just creating a markdown file, you will need to install some software.
You will need the following software
-
Python (2.7.9 or later) - This is required for the Sphinx package that will build our documentation:
-
If needed, install pip:
-
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 -
RestView - Optional, but makes it easy to preview ReStructured text files http://rst.ninjs.org/ or install:
$ pip install restview -
git - We use git to version control our documentation and manage with GitHub
You will need the following accounts
- GitHub account - Will make it possible to collaborate on the documentation:
-
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'
-
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 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.
-
Save your work as 'index.rst'
-
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 [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. We will also follow up about ensuring test data associated with the documentation are available and open.
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 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 |
|
| 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 |
|
This material is based upon work supported by the National Science Foundation under Grant No. #1827130. 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."