From add54d4855c239048c3a970aa86b0a3fec738d5a Mon Sep 17 00:00:00 2001 From: Christopher Bayliss Date: Tue, 12 May 2015 10:50:31 +1000 Subject: [PATCH 1/3] Convert the README to rst --- README | 147 --------------------------------------- README.rst | 199 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 199 insertions(+), 147 deletions(-) delete mode 100644 README create mode 100644 README.rst diff --git a/README b/README deleted file mode 100644 index 7cb239b..0000000 --- a/README +++ /dev/null @@ -1,147 +0,0 @@ -Introduction: -Zanata Python client is a client that communicates with a Zanata server -[http://zanata.org/] to push text for translation (from publican documents or -gettext-based software), and pull translated text back for inclusion in -software or documentation builds. - -It also provides support for creating projects/versions in Zanata and retrieving -information about projects. - -Install: -You can install the zanata-python-client with 'yum install zanata-python-client' - -To install from source: - make install - -Compiling: - -make lint: runs pylint against the source code. - -make test: runs unit tests. Note: To run the unit tests, you will also need minimock: 'yum install python-minimock' - -Configuration: -After you install the zanata-python-client, you need to create a global configuration file $HOME/.config/zanata.ini that contain user-specific configuration. -For creation of zanata.ini can be found on http://zanata.org/help/cli/cli-configuration/ - -For each project, you also have to write a project-specific configuration file named zanata.xml. -Sample zanata.xml file can be found on https://github.com/zanata/zanata-server/blob/master/zanata.xml - -You can also override the URL of the server with the command line option '--url'. -There are also command line options '--username' for user name and '--apikey' for api key of user. - -Command List: - -Name: /usr/bin/zanata - -Type "zanata" in the shell, it will give you basic information of command -for working with Zanata server. You can use "zanata --help" to get more -information about the commands of zanata. - -Basic Usage: zanata COMMAND [ARGS] [COMMAND_OPTIONS] - -Listing / Querying for Projects - -$ zanata list - -Creating a project - -$ zanata project create {project_id} --project-name={project_name} --project-desc={project_description} - -Create a Project Version - -$ zanata version create {version_id} --project-id={project_id} --version-name={version_name} --version-desc={version_description} - -Query for information of a project - -$ zanata project info --project-id={project_id} - -Query for information of a project iteration - -$ zanata version info --project-id={project_id} --project-version={version_id} - -Publishing Templates (source text) to Zanata - -If you want to push only one template file to zanata server, you can use command below: - -$ zanata publican push --project-id={project_id} --project-version={iteration_id} [documentName..] - -If documentName is omitted, 'publican push' command will push all the -template files under the template folder to Zanata server. You can -specify the path of template folder by command line option '--srcdir'. If -you don't provide such info, the command will try to locate template folder -in current path. - -$ zanata publican push --project-id={project_id} --project-version={iteration_id} --srcdir={template_folder} - -$ zanata publican push --project-id={project_id} --project-version={iteration_id} - -Or you can simply run below command in a folder contain template folder with zanata.xml, command will load all the info from configuration file: - -$ zanata publican push - -You can enable 'import-po' option, then related translation (po files) will be pushed to zanata server at the same -time. -You need to specify the parent folder that contain all the translation by 'transDir' command line option. By default, command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to push to the zanata server by 'lang' option - -$ zanata publican push --import-po --trandir={path of parent folder contains locale folders} --lang=lang1,lang2,.. - -By default, the server will try to find closest equivalent translation from oter versions in the same project and copy to version you specified. You can set no-copytrans to disable that function - -$ zanata publican push --no-copytrans - -Retrieving translated Documents from zanata - -If you want to retrieve only one file from zanata server, you can use command below: - -$ zanata publican pull --project-id={project_id} --project-version={iteration_id} [documentName..] - -Without indicate the documentName, this command will pull all the documents of a project version on zanata server to a local output folder. Command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to pull from the zanata server by 'lang' option - -$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder} - -$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. - -you can also simply running below command in a folder contain zanata.xml, command will load all the info from configuration file: - -$ zanata publican pull - -Push and pull software project with Zanata - -If you want to push only software project file to zanata server, you can use command below: - -$ zanata po push --project-id={project_id} --project-version={iteration_id} [documentName..] - -Without indicate the documentName, 'po push' command will push all source file of software under the po folder to zanata server. You can specify the path of po folder by command line option, if you don't provide such info, the command will try to locate po folder in current path - -$ zanata po push --project-id={project_id} --project-version={iteration_id} --srcdir={po_folder} - -$ zanata po push --project-id={project_id} --project-version={iteration_id} - -Or you can simply running below command in a folder contain po folder with zanata.xml, command will load all the info from configuration file: - -$ zanata po push - -You can enable 'import-po' option, then related translation will be pushed to zanata server at the same time. you can specify the parent folder that contain all the translation by 'transdir' command line option, or the client will use the path of po folder as the 'transdir'. By default, command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to push to the zanata server by 'lang' option - -$ zanata po push --import-po --trandir={path of parent folder contains translation files, such as zh-CN.po} --lang=lang1,lang2,.. - -By default the server will try to find closest equivalent translation from oter versions in the same project and copy to version you specified. you can set --no-copytrans option to disable that function. - -$ zanata po push --no-copytrans - -Retrieving Software project translation from zanata - -If you want to retrieve software translation from zanata server, you can use command below: - -$ zanata po pull --project-id={project_id} --project-version={iteration_id} [softwareName..] - -Without indicate the software name, this command will pull all the translations of a project version on zanata server to a local output folder. Command will read the language info from project configuration file 'zanata.xml', or you can specify the language that you want to pull from the zanata server by 'lang' option - -$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder} - -$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. - -you can also simply running below command in a folder contain zanata.xml, command will load all the info from configuration file: - -$ zanata po pull - diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..cb54218 --- /dev/null +++ b/README.rst @@ -0,0 +1,199 @@ +Introduction +============ + +Zanata Python client is a client that communicates with a Zanata server +[http://zanata.org/] to push text for translation (from publican documents or +gettext-based software), and pull translated text back for inclusion in +software or documentation builds. + +It also provides support for creating projects/versions in Zanata and +retrieving information about projects. + +Install +======= + +You can install the zanata-python-client with: + + ``$ yum install zanata-python-client`` + +To install from source: + + ``$ make install`` + +Compiling +========= + +To run pylint against the source code: + + ``$ make lint`` + +To do unit tests: + + ``$ make test`` + +.. Note:: To run the unit tests, you will also need minimock: ``yum install python-minimock`` + +Configuration +============= + +After you install the zanata-python-client, you need to create a configuration +file in $HOME/.config/zanata.ini that contains user-specific configuration. For +infomation on how to create a configuration file, go to: +http://zanata.org/help/cli-configuration/ + +For each project, you need to write a project-specific configuration file named +zanata.xml. An example can be found here: +https://github.com/zanata/zanata-server/blob/master/zanata.xml + +You can also override the URL of the server with the command line option +``--url``. Use ``--username`` for user name and ``--apikey`` for api key of +user. + +Command List +============ + +Name: ``/usr/bin/zanata`` + +If you type ``zanata`` in the shell, it will give you basic information for +working with a Zanata server. You can use ``zanata --help`` to get more help. + +Basic Usage: ``zanata COMMAND [ARGS] [COMMAND_OPTIONS]`` + +Listing/Querying for Projects + + ``$ zanata list`` + +Creating a project: + + ``$ zanata project create {project_id} --project-name={project_name} --project-desc={project_description}`` + +Create a Project Version: + + ``$ zanata version create {version_id} --project-id={project_id} --version-name={version_name} --version-desc={version_description}`` + +Query for information of a project: + + ``$ zanata project info --project-id={project_id}`` + +Query for information of a project iteration: + + ``$ zanata version info --project-id={project_id} --project-version={version_id}`` + +Publishing Templates (source text) to Zanata. + +If you want to push only one template file to zanata server, you can use +command below: + + ``$ zanata publican push --project-id={project_id} --project-version={iteration_id} [documentName..]`` + +If documentName is omitted, the ``publican push`` command will push all the +template files under the template folder to the Zanata server. You can specify +the path of template folder by command line option ``--srcdir``. If you don't +provide such info, the command will try to locate template folder in current +path. + + ``$ zanata publican push --project-id={project_id} --project-version={iteration_id} --srcdir={template_folder}`` + + ``$ zanata publican push --project-id={project_id} --project-version={iteration_id}`` + +Or if you run command below in a folder containing a template folder with +zanata.xml in it, it will load all the info from configuration file: + + ``$ zanata publican push`` + +You can use the ``import-po`` option and the related translation (po files) +will be pushed to zanata server at the same time. + +You need to specify the parent folder that contains all the translations by the +``transDir`` option. By default it will read the language info from the project +configuration file (zanata.xml), or you can specify the language that you want +to push to the zanata server by ``lang`` option: + + ``$ zanata publican push --import-po --trandir={path of parent folder contains locale folders} --lang=lang1,lang2,..`` + +By default, the server will try to find closest equivalent translation from +other versions in the same project and copy to version you specified. You can +set no-copytrans to disable that function: + + ``$ zanata publican push --no-copytrans`` + +Retrieving translated Documents from zanata. + +If you want to retrieve only one file from zanata server, you can use: + + ``$ zanata publican pull --project-id={project_id} --project-version={iteration_id} [documentName..]`` + +Without indicating the documentName, this command will pull all the documents +of a project version on zanata server to a local output folder. It reads the +language info from project configuration file (zanata.xml), or you can specify +the language that you want to pull from the zanata server by the ``--lang`` +option: + + ``$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder}`` + + ``$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,..`` + +You can also simply run this in a folder containing zanata.xml and it will load +all the info from configuration file: + + ``$ zanata publican pull`` + +Push and pull software project with Zanata + +If you want to only push a software project file to the zanata server: + + ``$ zanata po push --project-id={project_id} --project-version={iteration_id} [documentName..]`` + +Without giving the documentName, ``po push`` will push all source files of the +project under the po folder to zanata server. You can specify the path of the +po folder with ``--srcdir={po_folder_name}``, if you don't provide such info, +the command will try to locate the po folder in the current path: + + ``$ zanata po push --project-id={project_id} --project-version={iteration_id} --srcdir={po_folder}`` + + ``$ zanata po push --project-id={project_id} --project-version={iteration_id}`` + +Or you can simply run this in a folder containing a po folder with zanata.xml +and it will load all the info from configuration file: + + ``$ zanata po push`` + +You can use the ``--import-po`` option and related translations will be pushed +to the zanata server at the same time. You can specify the parent folder that +contains all the translations with +``--transdir={path_of_parent_folder_contains_translation_files}``, or the +client will use the path of po folder as the 'transdir'. By default, command +will read the language info from project configuration file (zanata.xml), or +you can specify the language that you want to push to the zanata server by +'lang' option + + ``$ zanata po push --import-po --trandir={path of parent folder contains translation files, such as zh-CN.po} --lang=lang1,lang2,..`` + +By default the server will try to find closest equivalent translation from oter +versions in the same project and copy to the version you specified. you can set +``--no-copytrans`` option to disable this function. + + ``$ zanata po push --no-copytrans`` + +Retrieving Software project translation from zanata + +If you want to retrieve the software translation from the zanata server, you +can use the command below: + + ``$ zanata po pull --project-id={project_id} --project-version={iteration_id} [softwareName..]`` + +Without indicating the software name, this command will pull all the +translations of a project version on the zanata server to a local output +folder. It reads the language info from project configuration file +(zanata.xml), or you can specify the language that you want to pull from the +zanata server by the ``--lang`` option: + + ``$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder}`` + + ``$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,..`` + +you can also simply run this in a folder containing a zanata.xml file and it +will load all the info from the configuration file: + + ``$ zanata po pull`` + From 0037b9676f0ca8de87be9873032f11e144a7508f Mon Sep 17 00:00:00 2001 From: Christopher Bayliss Date: Fri, 15 May 2015 16:18:43 +1000 Subject: [PATCH 2/3] Use nicer code blocks --- README.rst | 108 ++++++++++++++++++++++++++--------------------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/README.rst b/README.rst index cb54218..68aed36 100644 --- a/README.rst +++ b/README.rst @@ -12,24 +12,24 @@ retrieving information about projects. Install ======= -You can install the zanata-python-client with: +You can install the zanata-python-client with:: - ``$ yum install zanata-python-client`` + $ yum install zanata-python-client -To install from source: +To install from source:: - ``$ make install`` + $ make install Compiling ========= -To run pylint against the source code: +To run pylint against the source code:: - ``$ make lint`` + $ make lint -To do unit tests: +To do unit tests:: - ``$ make test`` + $ make test .. Note:: To run the unit tests, you will also need minimock: ``yum install python-minimock`` @@ -59,47 +59,47 @@ working with a Zanata server. You can use ``zanata --help`` to get more help. Basic Usage: ``zanata COMMAND [ARGS] [COMMAND_OPTIONS]`` -Listing/Querying for Projects +Listing/Querying for Projects:: - ``$ zanata list`` + $ zanata list -Creating a project: +Creating a project:: - ``$ zanata project create {project_id} --project-name={project_name} --project-desc={project_description}`` + $ zanata project create {project_id} --project-name={project_name} --project-desc={project_description} -Create a Project Version: +Create a Project Version:: - ``$ zanata version create {version_id} --project-id={project_id} --version-name={version_name} --version-desc={version_description}`` + $ zanata version create {version_id} --project-id={project_id} --version-name={version_name} --version-desc={version_description} -Query for information of a project: +Query for information of a project:: - ``$ zanata project info --project-id={project_id}`` + $ zanata project info --project-id={project_id} -Query for information of a project iteration: +Query for information of a project iteration:: - ``$ zanata version info --project-id={project_id} --project-version={version_id}`` + $ zanata version info --project-id={project_id} --project-version={version_id} Publishing Templates (source text) to Zanata. If you want to push only one template file to zanata server, you can use -command below: +command below:: - ``$ zanata publican push --project-id={project_id} --project-version={iteration_id} [documentName..]`` + $ zanata publican push --project-id={project_id} --project-version={iteration_id} [documentName..] If documentName is omitted, the ``publican push`` command will push all the template files under the template folder to the Zanata server. You can specify the path of template folder by command line option ``--srcdir``. If you don't provide such info, the command will try to locate template folder in current -path. +path:: - ``$ zanata publican push --project-id={project_id} --project-version={iteration_id} --srcdir={template_folder}`` + $ zanata publican push --project-id={project_id} --project-version={iteration_id} --srcdir={template_folder} - ``$ zanata publican push --project-id={project_id} --project-version={iteration_id}`` + $ zanata publican push --project-id={project_id} --project-version={iteration_id} Or if you run command below in a folder containing a template folder with -zanata.xml in it, it will load all the info from configuration file: +zanata.xml in it, it will load all the info from configuration file:: - ``$ zanata publican push`` + $ zanata publican push You can use the ``import-po`` option and the related translation (po files) will be pushed to zanata server at the same time. @@ -107,56 +107,56 @@ will be pushed to zanata server at the same time. You need to specify the parent folder that contains all the translations by the ``transDir`` option. By default it will read the language info from the project configuration file (zanata.xml), or you can specify the language that you want -to push to the zanata server by ``lang`` option: +to push to the zanata server by ``lang`` option:: - ``$ zanata publican push --import-po --trandir={path of parent folder contains locale folders} --lang=lang1,lang2,..`` + $ zanata publican push --import-po --trandir={path of parent folder contains locale folders} --lang=lang1,lang2,.. By default, the server will try to find closest equivalent translation from other versions in the same project and copy to version you specified. You can -set no-copytrans to disable that function: +set no-copytrans to disable that function:: - ``$ zanata publican push --no-copytrans`` + $ zanata publican push --no-copytrans Retrieving translated Documents from zanata. -If you want to retrieve only one file from zanata server, you can use: +If you want to retrieve only one file from zanata server, you can use:: - ``$ zanata publican pull --project-id={project_id} --project-version={iteration_id} [documentName..]`` + $ zanata publican pull --project-id={project_id} --project-version={iteration_id} [documentName..] Without indicating the documentName, this command will pull all the documents of a project version on zanata server to a local output folder. It reads the language info from project configuration file (zanata.xml), or you can specify the language that you want to pull from the zanata server by the ``--lang`` -option: +option:: - ``$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder}`` + $ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder} - ``$ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,..`` + $ zanata publican pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. You can also simply run this in a folder containing zanata.xml and it will load -all the info from configuration file: +all the info from configuration file:: - ``$ zanata publican pull`` + $ zanata publican pull Push and pull software project with Zanata -If you want to only push a software project file to the zanata server: +If you want to only push a software project file to the zanata server:: - ``$ zanata po push --project-id={project_id} --project-version={iteration_id} [documentName..]`` + $ zanata po push --project-id={project_id} --project-version={iteration_id} [documentName..] Without giving the documentName, ``po push`` will push all source files of the project under the po folder to zanata server. You can specify the path of the po folder with ``--srcdir={po_folder_name}``, if you don't provide such info, -the command will try to locate the po folder in the current path: +the command will try to locate the po folder in the current path:: - ``$ zanata po push --project-id={project_id} --project-version={iteration_id} --srcdir={po_folder}`` + $ zanata po push --project-id={project_id} --project-version={iteration_id} --srcdir={po_folder} - ``$ zanata po push --project-id={project_id} --project-version={iteration_id}`` + $ zanata po push --project-id={project_id} --project-version={iteration_id} Or you can simply run this in a folder containing a po folder with zanata.xml -and it will load all the info from configuration file: +and it will load all the info from configuration file:: - ``$ zanata po push`` + $ zanata po push You can use the ``--import-po`` option and related translations will be pushed to the zanata server at the same time. You can specify the parent folder that @@ -165,35 +165,35 @@ contains all the translations with client will use the path of po folder as the 'transdir'. By default, command will read the language info from project configuration file (zanata.xml), or you can specify the language that you want to push to the zanata server by -'lang' option +'lang' option:: - ``$ zanata po push --import-po --trandir={path of parent folder contains translation files, such as zh-CN.po} --lang=lang1,lang2,..`` + $ zanata po push --import-po --trandir={path of parent folder contains translation files, such as zh-CN.po} --lang=lang1,lang2,.. By default the server will try to find closest equivalent translation from oter versions in the same project and copy to the version you specified. you can set -``--no-copytrans`` option to disable this function. +``--no-copytrans`` option to disable this function:: - ``$ zanata po push --no-copytrans`` + $ zanata po push --no-copytrans Retrieving Software project translation from zanata If you want to retrieve the software translation from the zanata server, you -can use the command below: +can use the command below:: - ``$ zanata po pull --project-id={project_id} --project-version={iteration_id} [softwareName..]`` + $ zanata po pull --project-id={project_id} --project-version={iteration_id} [softwareName..] Without indicating the software name, this command will pull all the translations of a project version on the zanata server to a local output folder. It reads the language info from project configuration file (zanata.xml), or you can specify the language that you want to pull from the -zanata server by the ``--lang`` option: +zanata server by the ``--lang`` option:: - ``$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder}`` + $ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. --dstdir={output_folder} - ``$ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,..`` + $ zanata po pull --project-id={project_id} --project-version={iteration_id} --lang=lang1,lang2,.. you can also simply run this in a folder containing a zanata.xml file and it -will load all the info from the configuration file: +will load all the info from the configuration file:: - ``$ zanata po pull`` + $ zanata po pull From 7ee5242ce5e49fd4c174e11491f3b6689208b2da Mon Sep 17 00:00:00 2001 From: Christopher Bayliss Date: Mon, 18 May 2015 16:15:31 +1000 Subject: [PATCH 3/3] Add --url --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 68aed36..27dd25e 100644 --- a/README.rst +++ b/README.rst @@ -61,7 +61,7 @@ Basic Usage: ``zanata COMMAND [ARGS] [COMMAND_OPTIONS]`` Listing/Querying for Projects:: - $ zanata list + $ zanata list --url Creating a project::