This repo contains multiple guides that are hosted on Github Pages: https://cyverse.github.io/atmosphere-guides.
You can install the released .dmg built as part of Pandoc releases. You can find them on the release page.
Or, you can install via Homebrew:
brew install pandoc
More details are available on the Pandoc installing page.
For Linux, the suggestion is to try using the distributions package manager.
The Atmosphere development team favors Ubuntu, here is an example of installed within that distribution:
$ sudo apt-get install pandoc
This will install pandoc and pandoc-data.
More details are available on the Pandoc installing page.
Guides are written in Markdown. You may want to use a tool to render your Markdown. livedown works with a few editors to hot-load your changes. The atom editor also has built-in markdown preview.
Here is another tool to make nice GIFs. http://recordit.co/
After making changes to the Markdown source, you need to compile them to HTML, then push to the gh-pages branch, from which the static HTML is served.
First, you must have pandoc installed and in your executable path -- see Installing Pandoc.
If you create a new guide, you will also need to update the Makefile so that to_html_template.sh builds HTML for your new guide.
Finally, to compile the docs, run make from the root of this repository.
See CONTRIBUTING.md for Pandoc-specific details not covered here.
Static HTML is served on GitHub Pages from the gh-pages branch of this repository, which contains only the dist/ folder of the master branch. After pushing changes to master or merging in a pull request, the gh-pages branch will be automatically updated by the Travis CI deployment provider for GitHub Pages. This automation only works for cyverse/atmosphere-guides repo at the moment.
If you would like to publish your dist folder to your fork's gh-pages:
# Overwrite your remote's gh-pages
git push -f <your remote> "$(git subtree split --prefix dist)":gh-pages
A lot of Atmosphere documentation lives on the CyVerse Wiki, some in the Atmosphere Manual and some in private spaces. Going forward, documentation should be maintained as follows:
- Docs for Atmosphere(1) as the open-source platform for cloud computing should be hosted here on atmosphere-guides, and what exists on the CyVerse wiki should be migrated here.
- Docs for Atmosphere(0) as CyVerse's cloud computing service for bioscience research should remain on the CyVerse wiki, in Atmosphere Manual or other spaces as appropriate.
When you do migrate content from the CyVerse wiki to atmosphere-guides, please remove the content from the wiki and leave a link to the new guide in its place. This way, we avoid maintaining parallel documentation on multiple platforms, while helping others find information in its new location.