11.2.1. Organisation of the Manual in Git¶

The FG manual has been developed by many different groups and we try to provide a consistant set of manual pages as much as possible. The manual is located in the directory:

docs/source

Here you will find the many RST files contributed by the team members. To simplify editing and to keep the number of conflicts during editing to a minimum it is naturally a good idea to have many such files. However, all of them are integrated via the file:

docs/source/index.rst

into a single manual. Due to this organization it is also possible to create custom manuals that may suport a particular class. For example a class on big data may not be wanting to use MPI and thus a special manual for such a class could be created. The nice thing is that the teacher does not have to create additional information, but can just use sphinx and a special index rst file to create a customized manual of interest.

Please note that at this time we have also additional documented rst files not yet included into the manual as they were not yet reviewed.

11.2.2. Online Editing for Novice Editors¶

If you are part of the FG manual development team you can edit the manual pages online by going to:

https://github.com/futuregrid/manual/tree/master/docs/source

This will contain a directory with all the documents of the manual. You can find the names of the documents by visiting the manual, looking at the URL of the page that you would like to modify, openng up the corresponding rst page (e.g. replace the html with rst). Dependent on your browser you can even configure it to open the file in your favorite editor. Some plugins such as It’s All Text! may be able to help.

• https://addons.mozilla.org/en-US/firefox/addon/its-all-text/

Please consult with your browsers manual and available plugins. However, a better solution may be to do the changes in a clone locally and commit when ready. This is documented in more detail in this section.

11.2.3. FAQ¶

• How to find the rst file?
  • Sometimes an editor may want to locate the name of the rst file. This is easy, just look in your browser, and see the url’s, the last filename with a .html ending gives your the rst file name, just replace html with rst
• Can I edit RST files in Word?
  • yes you can, but you must make sure that you do use the proper ascii characters for quotes and other symbols that RST relies on.
• Can I edit RST files directly in a Web browser without word
  • Yes you can, you must have a git account for that and you can editd directly?
• I do not have a Git account how do I communicate errors?
  • Either Send us the url of the manual page with an error, copy the “before text”, add a “changed to” text and e-mail it to us
  • Or, create a git clone and send us the patch. More information about this can be found in the git user manual on github.com
• Why use RST?
  • Previously pages of the FG manual were edited directly in drupal on our portal. However, editors were abusing our wysiwyg editor by pasting and copying text from third party editors such as word into the drupal editor. Unfortunately, this lead to inconsistent formatting and severe problems by editing documents. We also discovered issues at times when documents were edited by multiple editors at the same time.
  • While using RST we avoid inconsistent formatting.
  • While using git we use a much better tracking feature for parallel edits,
  • While using RST we have a nice search feature.
  • While using RST we can integrate auto-generate documentation form FutureGrid code we develop such as RAIN and cloudmesh.
• Why not use Word and skydrive?
  • Our team has rich experience with skydrive and Word. However word does not provide a publication framework for our manual that is maintained by a highly distributed team. Although skydrive can be a help to share directories, we still have to enable the creation of a single consistent manual. We also experienced issues with large groups on microsoft skydrive. As most contributions come from developers that have already accounts on github, they do not have to create new accounts on skydrive. Furthermore, not all developers have access to word. However RST documents are editor independent. You can edit them with Word, emacs, vi, vim, or whatever other text editor you like. Thus the good news is if you like to use word to edit the documentation you can.
• I am having difficulties understanding this.How can I get help?
  • Please contact Gregor von Laszewski at laszewski@gmail.com. He can schedule an in person meeting in Bloomington, IN or a google hangout meeting.

11.2.4. Publication of the Manual¶

The manual will be automatically updated once a day

Additionally you can e-mail laszewski@gmail.com for an update request while describing which files have been changed so a review can take place and the publication script can be invoked. We have not put this script into the repository in order to avoid accidental changes.

11.3.1. Python¶

Make sure you have python 2.7.2:

$ python --version

Please note that we have not tried python version 3 for this.

11.3.2. Virtualenv¶

Make sure the is no book directory in your home

Use virtual env:

$ cd ~
$ virtualenv MANUAL
$ source MANUAL/bin/activate

In case you were to use another terminal (for example quit this one and start a new one later), please remember to execute:

$ source MANUAL/bin/activate

11.3.3. Create a github local directory with the manual¶

We assume you will install your local copy of the manual in ~/github/manual. If you do not want to use the github dir, please use another directory name you like:

$ mkdir -p ~/github
$ cd ~/github
$ git clone https://github.com/futuregrid/manual.git

11.3.4. Install the Requirements¶

To build this book make sure you install the following module:

$ cd manual
$ pip install -r requirements.txt

This may take a while, so be patient.

The files will be in:

./docs/source

and have an rst ending. They use restructured text. For more info on rst see:

• http://sphinx-doc.org/rest.html

A cheat sheet is available from

http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf

The cheatsheet is also available in our online documentation in the Section RST CHEATSHEET.

11.3.5. All-in-one setup script¶

Execute the following script only with care. Maybe its best if you copy one line at a time as documented earlier to avoid problems:

cd ~
virtualenv MANUAL
source MANUAL/bin/activate
mkdir -p ~/github
cd ~/github
git clone https://github.com/futuregrid/manual.git
cd manual
pip install -r requirements.txt

11.3.6. Watchdog¶

This tool is optional and can be skipped for those just doing a regular install.

You may be interested in using watchdog when you are in the process of editing a page. Upon chnage it will update the changed html output into the browser. For example, assume you edit the page openstack.rst. If you are running in another window:

make watchdog FILE=openstack

For more details, please see the Makefile.

11.3.7. Transfering a page from the portal to RST¶

Assume you like to transfer a page from the portal to rst. This can actually be done quite easily using a program called pandoc. First get the page and rename it to a page with html:

$ wget https://portal.futuregrid.org/contrib/simple-vine-tutorial
$ mv simple-vine-tutorial simple-vine-tutorial.html
$ pandoc simple-vine-tutorial.html -o simple-vine-tutorial.rst

Than edit the page and remove the code related to the menues so only the bare code stays:

• typically everything before What links here can be ignored.

• typically everything after the words Your rating and the rest

  of the page can be ignored.

11.3.8. Creating the pages locally¶

To create the pages locally simply go in the manual folder and saay make:

$ cd ~/github/manual
$ make

Your index file will be in:

$ firefox ./docs/build/html/index.html

On Osx you can simply say:

$ make view

11.3.9. Publishing the pages¶

The pages can be published to github with:

make gh-pages

11.3.10. Jira¶

References to jira can be made with the tag:

:jira:`this issue <FG-1418>`

It will result in an output such as

this issue

To just refer to a text with the number use:

:jira:`FG-1418`

and you will get

issue FG-1418

It uses the extension http://sphinx-doc.org/latest/ext/extlinks.html and the tags must be specified in the conf.py file.

11.3.11. Portal link¶

to simplify access to a portal url you can use:

:portal:`my/ssh-keys`

and it will return

https://portal.futuregrid.org/my/ssh-keys

It uses the extension http://sphinx-doc.org/latest/ext/extlinks.html and the tags must be specified in the conf.py file.

11.3.12. Screencast recording tips¶

$ defaults write com.apple.finder CreateDesktop -bool false
$ killall Finder

$ defaults write com.apple.finder CreateDesktop -bool true
$ killall Finder

$ PS1="$ "

$ script file.log