Merge pull request #44 from zanata/readthedocs

Add Read the docs documentation.

docs/commands/init.md

@@ -0,0 +1,47 @@
+# Command: init
+
+To initialise a project from the command line, the `init` command can be used. This command will guide you through the steps necessary to set up a new or existing project, and start using Zanata.
+
+These instructions assume that you have installed zanata-cli version 3.4.0 or higher as shown in [Installing the Client](installation).
+
+
+
+## Getting started
+
+The first thing to do is to type the following command in the console: `zanata-cli init`
+
+The client will proceed to ask which of your preferred Zanata servers it needs to use to register your new project (this information is taken from your `zanata.ini` file; if the desired server does not appear in the list, it should be added to this file).
+
+```bash
+[INFO] Loading project config from zanata.xml
+[INFO] Loading user config from /home/camunoz/.config/zanata.ini
+    Found servers in zanata.ini:
+    1)    http://localhost:8080/zanata/
+    2)    https://translate.jboss.org/
+    3)    https://translate.zanata.org/zanata/
+[?] Which Zanata server do you want to use?
+```
+
+Select the Zanata server to use by typing in the number and hiting ENTER. The client will now ask whether you want to create a new project, or use an existing one from your instance:
+
+```bash
+[?] Do you want to 1) select an existing project or 2) create a new one (1/2)?
+```
+
+According to your selection the client will ask for information about your new project and proceed to create it, or it will give you an option to select an existing one from the server.
+
+```bash
+[?] What project ID/slug do you want to have (must start and end with a letter or number, and contain only letters, numbers, underscores and hyphens):
+$ my-project-id
+[?] What project name do you want to have:
+$ My Project Name
+[?] What is your project type ([utf8properties, properties, gettext, podir, xliff, xml, file])?
+$ podir
+[>] Project created. Now it's time to create a version to host your files.
+
+[?] What version ID/slug do you want to have:
+$ master
+[>] Version created.
+```
+
+the Zanata client will continue to ask questions and provide information on the next steps necessary to get you started with your project on Zanata.

docs/commands/pull.md

@@ -0,0 +1,43 @@
+# Command: pull
+
+To download documents from your project-version, the command-line client's `pull` command can be used.
+
+These instructions assume that you have installed zanata-cli as shown in [Installing the Client](installation), and have saved user and project configuration as shown in [Configuring the Client][configuration].
+
+
+## Translation Document Download
+
+The basic command for downloading documents is `zanata-cli pull`. The pull command should always be run from the directory that contains `zanata.xml` for your project (find information about `zanata.xml` at [Configuring the Client][configuration]).
+
+At the time of writing, you will have to specify source and translation directories with the command, even though the default pull command will pull only translated documents from the server. This will be fixed in a future version. This means that the simplest pull command is:
+
+```bash
+zanata-cli pull -s src -t trans
+```
+
+
+This command will:
+
+ 1. look up the locales to pull from `zanata.xml` (all the enabled locales by default).
+ 1. display the current settings and list of locales that will be downloaded.
+ 1. confirm that you want to proceed with the download.
+ 1. download translated versions of any documents that have any translations.
+
+Documents with no translations will not be downloaded unless specifically requested by adding the `--create-skeletons` option.
+
+To download only a few locales, use the `-l` or `--locales` option. For example, to download only Japanese and Russian translations, I might run `zanata-cli pull -s src -t trans -l ja,ru`. You can also modify the locales in `zanata.xml` if you will be consistently specifying a different set of locales.
+
+For a full list of the available options for pull, run `zanata-cli help pull`
+
+
+## Source Document Download
+
+The pull command can also download source documents. This is generally only for reference purposes since source documents cannot be changed on the server.
+
+To pull translations instead of source documents, add the option `--pull-type source`, like so:
+
+```
+zanata-cli pull --pull-type source -s src -t source
+```
+
+To pull source and translation documents together, use `--pull-type both`.

docs/commands/push.md

@@ -0,0 +1,62 @@
+# Command: push
+
+To upload documents to your project-version, the command-line client's `push` command can be used.
+
+These instructions assume that you have installed zanata-cli as shown in [Installing the Client](installation), and have saved user and project configuration as shown in [Configuring the Client][].
+
+
+
+## Source Document Upload
+
+The basic command for uploading documents is `zanata-cli push`. The push command should always be run from the directory that contains `zanata.xml` for your project (find information about `zanata.xml` at [Configuring the Client][configuration]).
+
+At the time of writing, you will have to specify source and translation directories with the command, even though the default push command will push only source documents to the server. This will be fixed in a future version. This means that the simplest push command is:
+
+`zanata-cli push -s src -t trans`
+
+This command will:
+
+ 1. search for source documents in a directory named `src` and any of its subdirectories.
+ 1. display the current settings and list of source documents that were found.
+ 1. confirm that you want to proceed with the upload.
+ 1. upload the located source documents to the server.
+
+*Note:* if your source files are in the same directory as non-source files that have the same extension, such as when using Java `.properties` files for both translation and configuration, the `--includes` or `--excludes` option should be used to tell Zanata which files it should push.
+
+For a full list of the available options for push, run `zanata-cli help push`
+
+
+## Translation Document Upload
+
+The push command can also upload translations. This is mainly for use when translation has started on your project before it has moved to Zanata. Translators can also use this command to upload translations, although translation on the Zanata website is safer.
+
+To push translations instead of source documents, add the option `--push-type trans`, like so:
+
+```bash
+zanata-cli push --push-type trans -s src -t trans
+```
+
+To push source and translation documents together, use `--push-type both`.
+
+These commands will upload all available translations for the locales specified in `zanata.xml`, unless the `-l` or `--locales` option is used to specify a smaller set of locales. For example: `-l ja,de`.
+
+*Note:* translation documents must be named appropriately to match a source document. The appropriate name depends on your project type. For example, if the above command is used for a Java Properties project with a source document `src/strings/messages.properties`, a Japanese translation for the document would be at `trans/strings/messages_ja.properties`.
+
+```bash
+src
+  strings
+    messages.properties
+trans
+  strings
+    messages_ja.properties
+```
+
+If you are unsure about the layout and naming for translation files in the selected project type, you can do a trial pull and look at the output. This can be done by copying `zanata.xml` to an empty folder and running a pull command such as:
+
+```bash
+zanata-cli pull -s src -t trans --create-skeletons
+```
+
+The option `--create-skeletons` is used to make sure files will be written even if there are no translations.
+
+For more information on the pull command, see [Document Download with Client](commands/pull).

docs/configuration.md

@@ -0,0 +1,122 @@
+# Configuring the Client
+
+zanata-cli requires User Configuration and Project-Version Configuration.
+
+## User Configuration
+
+User configuration stores your credentials so that zanata-cli can prove to the server that requests are from you rather than an imposter. The information in your user config should be kept secret.
+
+zanata-cli expects to find user configuration in `.config/zanata.ini` within your user directory.
+
+To add configuration for a Zanata server:
+
+ 1. Use your favourite text editor to create or open `zanata.ini` in `~/.config/`.
+ 1. Sign into the Zanata server and navigate to the user settings page
+ 1. Ensure that an API Key is shown. If you do not have an API Key, click 'Generate API Key' now.
+![User settings page](images/302-user-settings.png)
+
+ 1. Copy the contents of the text-box labeled 'Configuration [zanata.ini]'.
+ 1. Paste the copied lines into `zanata.ini` and save the file.
+
+
+## Project-Version Configuration
+
+Project configuration stores information about a project-version, and should be kept in the project directory.
+
+zanata-cli expects to find project-version configuration in a file named `zanata.xml` in the project directory.
+
+To add project-version configuration to your project directory:
+
+ 1. Sign into the Zanata server and navigate to the appropriate version of your project.
+ 1. Click the `Download config file` link to initiate download of `zanata.xml`.
+![Download config file link on version page](images/350-version-config-file.png)
+
+ 1. Save `zanata.xml` in your project directory.
+
+
+These steps should be repeated for each project-version before using any zanata-cli commands for the project-version.
+
+You can customize `zanata.xml` with command hooks so that other tools will automatically run before or after Zanata commands. Read about command hooks at the [command hook page on the wiki](https://github.com/zanata/zanata-server/wiki/Client-Command-Hooks).
+
+
+## Locale Configuration
+
+The `zanata.xml` will contain a list of locales so that the client knows which locales to push and pull to/from the Zanata server. When downloaded from the Zanata server, the list will have the locales as specified by the server itself. It will look something like this:
+
+```xml
+<locales>
+  <locale>es</locale>
+  <locale>ja</locale>
+  <locale>fr</locale>
+  <locale>zh-Hant-TW</locale>
+  ...
+</locales>
+```
+
+Sometimes the way locales are named in your project files doesn't match Zanata's locale nomenclature, so it's necessary to create a mapping between the two. You can achieve this in the client by modifying the locale entries in `zanata.xml`.
+
+For instance, if one of your files is called `myfile/es.po` and your project in Zanata has the `es-ES` locale, then your client mappng would look like this:
+
+```xml
+  <locale map-from='es'>es-ES</locale>
+```
+
+### Translation files mapping rules
+
+You can also customize the way translation files are found when pushing, as well as the location they will be saved to when pulling.
+{% highlight xml %}
+<!-- example rules definition in zanata.xml -->
+<rules>
+  <rule pattern="**/pot/*.pot">{locale}/{path}/{filename}.po</rule>
+  <rule pattern="**/po/*.pot">{path}/{locale_with_underscore}.po</rule>
+</rules>
+{% endhighlight %}
+
+In the example above, `pattern` identifies a source file, and the contents of the `rule` element specify how translation files will be stored.
+
+The `pattern` attribute is a [glob](http://en.wikipedia.org/wiki/Glob_(programming)) matching pattern to your source document file(s). You can define more than one rule and apply each rule to a specific set of source documents using different patterns. The **first** matched rule will be applied to the file. 
+
+`pattern` is optional. If not specified, the rule will be applied to all source documents in your project.
+The actual rule consists of literal path and placeholders/variables.
+
+Supported placeholders/variables are:
+
+ 1. **{path}** is the path between source document root (what you define as src-dir option) and the final file.
+ 1. **{filename}** the source document name without leading path and extension.
+ 1. **{locale}** the locale for the translation file. If you use "map-from" argument in your locale mapping, this will be the map-from value.
+ 1. **{locale\_with\_underscore}** same as above except all hyphens '-' will be replaced with underscores '_'. This is typically used in properties and gettext projects.
+ 1. **{extension}** the source document file extension
+
+For example, given a source document is found at `/home/user/myproject/src/main/resource/message.properties` 
+
+... and your source document root (src-dir option) is set to "." 
+
+... Your zanata.xml is located at `/home/user/myproject` 
+
+... For a locale mapping defined as `<locale map-from="zh-CN">zh</locale>`: 
+
+
+The following placeholders will be detected:
+
+```
+{path}                     = 'src/main/resource'
+{filename}                 = 'message'
+{locale}                   = 'zh-CN'
+{locale\_with\_underscore} = 'zh_CN'
+{extension}                = 'properties' 
+```
+
+
+The mapping rules configuration is optional in zanata.xml. If not specified, standard rules are applied according to your [project type](https://github.com/zanata/zanata-server/wiki/Project-Types).
+
+ 1. gettext: `{path}/{locale_with_underscore}.po`
+ 1. podir: `{locale}/{path}/{filename}.po`
+ 1. properties: `{path}/{filename}_{locale_with_underscore}.{extension}`
+ 1. utf8properties: `{path}/{filename}_{locale_with_underscore}.{extension}`
+ 1. xliff: `{path}/{filename}_{locale_with_underscore}.{extension}`
+ 1. xml: `{path}/{filename}_{locale_with_underscore}.{extension}`
+ 1. file: `{locale}/{path}/{filename}.{extension}`  
+
+---
+
+[Old instructions](https://github.com/zanata/zanata-server/wiki/Client-Configuration)

docs/index.md

@@ -0,0 +1,34 @@
+Zanata Command line Client
+=============
+
+The Zanata Command line client (CLI) is the perfect way to connect to a Zanata server to
+push and pull content.
+
+Features
+--------
+
+- Initialize a Translation project from the command line.
+- Push source content to the Zanata server.
+- Pull translated content from the Zanata server.
+
+Installation
+------------
+
+For installation instructions please see the [Installation Section](installation)
+
+Contribute
+----------
+
+- Issue Tracker: http://bugzilla.redhat.com
+- Source Code: github.com/zanata/zanata-client
+
+Support
+-------
+
+If you are having issues, please let us know.
+We have a mailing list located at: zanata-users@redhat.com
+
+License
+-------
+
+The project is licensed under the BSD license.

docs/installation.md

@@ -0,0 +1,43 @@
+# Installation
+
+The Zanata client (zanata-cli) can be installed on most systems. Installation is easiest under Fedora, other systems can use Apache Ivy for installation. Manual installation is also possible.
+
+
+## Installation on Fedora
+
+If you are using Fedora, zanata-cli is available through the `yum` package manager.
+
+```bash
+sudo yum install zanata-client
+```
+
+## Installation with Ivy
+
+The Ivy distribution of the client is a small script that will download the client the first time it is run. This distribution requires Apache Ivy to run.
+
+Instructions for installing Apache Ivy and the Ivy version of zanata-cli can be found at [Zanata Ivy Client on github](https://github.com/zanata/zanata-client-ivy).
+
+*Note:* The Ivy client will download required files the first time it is run, which may take several minutes. It will show `resolving dependencies...` while this is happening.
+
+## Manual Installation
+
+To manually install zanata-cli:
+
+ 1. Navigate to [zanata-cli on Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.zanata%22%20AND%20a%3A%22zanata-cli%22).
+ 1. Download either `dist.zip` or `dist.tar.gz`.
+
+ 1. Extract the contents of the archive to your location of choice.
+ 1. Create a symbolic link to the `zanata-cli` script in the bin directory of the extracted archive. e.g. from the archive directory, run `sudo ln -s bin/zanata-cli  /usr/local/bin/zanata-cli`.
+
+ 1. (optional) you can also enable tab-autocomplete for the client if you use bash as your terminal shell. This can be done by copying or linking the `zanata-cli-completion` script from the bin directory to `/etc/bash_completion.d/`. e.g. `ln -s bin/zanata-cli-completion /etc/bash_completion.d/zanata-cli-completion`.
+
+## Nightly Builds
+
+If you like to live dangerously, the client nightly relase is available. This may have newer features, but is not guaranteed to be stable.
+
+The latest nightly build is available as an archive that can be installed manually. To install the latest nightly build:
+
+ 1. Open [Client nightly builds](http://repository-zanata.forge.cloudbees.com/snapshot/org/zanata/zanata-cli/).
+ 1. Open the directory showing the highest version number.
+ 1. Download either of the distributable archives (ending with `-dist.zip` or `-dist.tar.gz`).
+ 1. Install as per manual installation instructions above.