Merge pull request #9 from kathryngo/review-readthedocs

Review: readthedocs for zanata-plugin

docs/configuration/build-step/install-cli.md

@@ -1,8 +1,7 @@
-### Things to note
-Most likely you will need to install [Credentials Binding Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Credentials+Binding+Plugin).
-
 ### Zanata CLI Installation
 
+_NOTE:_ You will need to install [Credentials Binding Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Credentials+Binding+Plugin) to use this option.
+
 ##### Global Configuration
 - Go to 'Manage Jenkins'
 - Go to 'Global Tool Configuration' (For Jenkins 1.6.x, tools configuration is under 'Configure System')
@@ -33,16 +32,18 @@ Under 'Build Environment' section:
 ![Install Zanata CLI for a job](/images/job_installs_cli.png)
 </figure>
 
-### Use the installed Zanata CLI in build
+### Use the installed CLI in build
 
 You can use it in two ways:
 
 1. Add a build step such as 'Execute shell' and invoke Zanata CLI in it (see [below example](/configuration/build-step/install-cli/#example-execute-shell-step-using-zanata-cli))
 2. Choose another build step [Zanata Sync via CLI](/configuration/zanata-sync-via-cli/)
 
-##### Example Execute shell step using Zanata CLI
-Assuming you follow [above configuration](/images/job_installs_cli.png) and chose 'zanata_cli_4_0_0' and checked convert to uppercase,
-Below shell script will do zanata push and pull and then git commit:
+##### Example: Execute shell step using Zanata CLI
+Assuming you follow the [above configuration](/images/job_installs_cli.png) and 
+have chosen 'zanata_cli_4_0_0' and checked convert to uppercase,
+the shell script below will do zanata push and pull and then git 
+commit:
 ```bash
 Z=$ZANATA_CLI_4_0_0_HOME/bin/zanata-cli
 

docs/configuration/build-step/zanata-sync-via-cli.md

@@ -1,4 +1,5 @@
-### Alternative build step (experimental and subject to change without notice)
+### Alternative build step 
+####(experimental and subject to change without notice)
 
 From Yu Shao [email protected]
 
@@ -8,11 +9,12 @@ From Yu Shao [email protected]
 - Go to 'Configure System'
 - Scroll down to find 'Zanata cli script template'
 
-There are two fields under 'Zanata cli script template', each of them contains a script template to use in your job.
+There are two fields under 'Zanata cli script template'. Each of them contains
+ a script template to use in your job.
 
 ##### Things to note
 
-The default script templates expect:
+The default script templates expect the following:
 
 - zanata username to be provided in an environment variable 'ZANATA_USERNAME', 
 and zanata API key provided in environment variable 'ZANATA_APIKEY'.
@@ -26,9 +28,14 @@ See [CLI installation](/configuration/build-step/install-cli/) for how to instal
 - Select Zanata credentials from the dropdown and it will automatically expose ZANATA_USERNAME and ZANATA_APIKEY to environment variables
 - Fill in 'Extra PATH entries' with the installed Zanata CLI location (e.g. *cli_name*_HOME/bin)
 
-Configure the sync details, there are two sync actions in the plugin, one, pushing the English source file(s) to Zanata server defined in zanata.xml file in the source repo property directories.  Two, committing the finished translation files from Zanata to the original Git repository. 
+Configure the sync details using one of the two sync actions in the plugin. 
+The first pushes the English source file(s) to the Zanata server defined in the
+zanata.xml file in the source repo property directories.  The second involves 
+committing the finished translation files from Zanata to the original Git repository.
 
-Both two types of sync are running the default shell scripts, you could customize the shell scripts, you could customize the two sync actions according to your build need by enabling or disabling them
+Both types of sync run the default shell scripts. You can customize the 
+shell scripts and the two sync actions according to your build needs by 
+enabling or disabling them.
 
 
 Example configuration:

docs/configuration/build-step/zanata-sync.md

@@ -14,7 +14,7 @@ Here you can:
 
 - Choose the Zanata credential for your Zanata Server
 - Choose to push source to Zanata and/or pull translation from Zanata
-- Click on 'Advanced Options' to reveal more advanced options
+- Click on 'Advanced Options' to reveal more options
 
 If you choose pull translation from Zanata, it will commit any changes if SCM is git.
 If you are not using git, you will need to configure a step yourself to do it.

docs/configuration/index.md

@@ -9,32 +9,35 @@
 ##### Global Configuration in your Jenkins server
 
 - Configure Zanata credentials (username and API key) in Jenkins Credentials view 
-- Add your github credential or equivalent remote SCM credentials if you want to push commit
-- JAVA_HOME defined as environment variable (You could configure Jenkins to install JDKs and then expose one installation's path as environment variable. This way the JAVA_HOME variable is correct both in master and in slave)
+- Configure Github credential or equivalent remote SCM credentials if you want
+ to push commit
+- JAVA_HOME defined as environment variable (You should install JDKs and then expose one's installation path as environment variable. This way the JAVA_HOME variable is correct both in master and in slave)
 
 ### Next step
 
 ##### Configure a job to listen to Zanata webhook event
 
-In your job configuration, check the *Accept Zanata Webhook* checkbox under 'General' section, it will open up more fields:
-
-- The 'URL to register on Zanata' filed is a readonly field for you to register webhook in Zanata. See [Zanata webhook](http://docs.zanata.org/en/release/user-guide/projects/project-settings/#adding-a-new-webhook) for more detail.
-- The optional webhook secret for verification of incoming webhooks
+In your job configuration, check the *Accept Zanata Webhook* checkbox under 
+'General' section. It will open up more fields:
+- The 'URL to register on Zanata' field is readonly for you to register your
+webhook in Zanata. See [Zanata webhook](http://docs.zanata.org/en/release/user-guide/projects/project-settings/#adding-a-new-webhook) for more detail.
+- The optional webhook secret field is for verification of incoming webhooks
 <figure>
-[![Accept Zanata Webhook](/images/zanata_webhook.png)](/images/zanata_webhook.png)
+![Accept Zanata Webhook](/images/zanata_webhook.png)
 </figure>
 
-Configure your SCM as per Jenkins job usual.
-
-If you want to trigger a build when SCM changes, you can leverage other Jenkins plugin.
-e.g. github plugin to listen to github webhook event and trigger a build to push resources to Zanata.
+Configure your SCM for your Jenkins job as usual.
+If you want to trigger a build when SCM changes, you can leverage other 
+Jenkins plugins.
+e.g. Github plugin to listen to github webhook event and trigger a build to 
+push resources to Zanata.
 
 Then in the 'Build' section, you will have two options to push source to and/or pull translation from Zanata server.
 
-1. [Use the plugin as a build step](/configuration/build-step/zanata-sync/)    
-2. [Install Zanata CLI on Jenkins node and use scripting to invoke it](/configuration/build-step/install-cli/)
+1. [Use the plugin as a build step](/configuration/build-step/zanata-sync)    
+2. [Install Zanata CLI on Jenkins node and use scripting to invoke it](/configuration/build-step/install-cli)
 
-Option 1 has the advantage of being installation free and simple to use. It will work on all type of jenkins slave nodes (windows and linux).
+Option 1 has the advantage of being installation free and simple to use. It will work on all type of jenkins slave nodes.
 It will commit translation after pull automatically if you use Git as SCM. 
 Disadvantage being that it uses only the included version of Zanata CLI java classes. and you can't do much customization for push and pull.
 

docs/installation.md

@@ -7,7 +7,7 @@
 ## Install manually
 
 In case your Jenkins server is configured to use a different update center, 
-and Zanata Jenkins Plugin is not in it. 
+and Zanata Jenkins Plugin is not in it:
 
 - Go to [Plugin Home](https://wiki.jenkins-ci.org/display/JENKINS/Zanata+Plugin) and click on the Latest Release to download the zanata.hpi file
 - Go to 'Manage Plugins' page