Updating docs

Touch #12

README.rst

@@ -1,7 +1,9 @@
 Pootle FS
 ---------
 
-Pootle FS app
+Pootle FS app provides a plugin framework for synchronizing external
+filesystems containing localisation files.
+
 
 .. image:: https://img.shields.io/travis/translate/pootle_fs.svg?style=flat-square
     :alt: Build Status
@@ -20,31 +22,29 @@ staged with any or all of:
 - ``add_translations``
 - ``fetch_translations``
 - ``rm_translations``
+- ``merge_translations``
 
 Changes to previously synced Stores/files are automatically staged for
 synchronisation, where no conflict exists.
 
 Once the desired changes have been staged ``sync_translations`` is called to
 perform the synchronisation.
 
-The workflow for bringing translations from FS into Pootle is:
 
-.. code-block::
-   
-   fetch_translations  >>>  sync_translations
+Installation
+============
 
-Where ``fetch_translations`` will stage the importable translations, and
-``sync_translations`` will actually sync to the database.
+``pootle_fs`` does not provide any specific plugins so need to install
+a backend plugin also.
 
+Currently the only implemented plugin is for `Git <./docs/plugins/git.rst>`_
 
-The workflow for sending translations from Pootle to the FS:
+Neither ``pootle_fs`` nor ``pootle_fs_git`` are on Pypi so only dev install
+is possible.
 
-.. code-block::
-   
-   add_translations  >>>  sync_translations
+Also requires the ``no_mtime`` branch of pootle:
 
-Where ``add_translations`` will stage the exportable translations, and
-``sync_translations`` will actually sync to the FS.
+`<https://github.com/phlax/pootle/tree/no_mtime>`_
 
 
 Further reading
@@ -55,6 +55,7 @@ Further reading
 - `Status <docs/status.rst>`_
 - `Commands <docs/commands.rst>`_
 - `Response <docs/response.rst>`_
+- `Git plugin <docs/plugins/git.rst>`_
 
 
 Related software

docs/configuration.rst

@@ -3,35 +3,56 @@
 Pootle FS Configuration
 -----------------------
 
-Configuring your project
-========================
+Configuring your project in Pootle
+==================================
 
 To set an FS plugin for a project, use the ``set_fs`` command:
 
 .. code-block:: bash
 
-   pootle fs $projectname set_fs $fs_type $fs_url
+   pootle fs MYPROJECT set_fs FS_TYPE FS_URL
 
-The ``$projectname`` must the name of a valid project in Pootle.
+``MYPROJECT`` must the name of a valid project in Pootle.
 
-The ``fs_type`` should be an installed and registered FS plugin type - such
+``FS_TYPE`` should be an installed and registered FS plugin type - such
 as ``git`` or ``local``.
 
-The ``fs_url`` must be a URL specific to the type of FS plugin you are using.
+``FS_URL`` must be a URL specific to the type of FS plugin you are using.
 
 
-Default configuration options in .ini file
-==========================================
+Creating a .pootle.ini on your filesystem
+=========================================
 
-.. code-block:: ini
+When pootle_fs first pulls your filesystem it looks for a file ``.pootle.ini``
+to set up the configuration of your project.
+
+The configuration file uses the ``ini`` syntax.
+
+You can see the current configuration for your project as follows:
+
+.. code-block:: bash
+
+   pootle fs MYPROJECT config
+
+
+Updating the configuration
+==========================
+
+If you make changes to your ``.pootle.ini`` file they do not take affect until
+you have updated the configuration:
+
+.. code-block:: bash
+
+   pootle fs MYPROJECT config --update
 
-   [default]
-   translation_path = /<lang>/<directory_path>/<filename>.po
 
 
 Defining a translation_path
 ===========================
 
 
+
+
 Defining a directory path
 =========================
+

docs/index.rst

@@ -0,0 +1,36 @@
+Pootle FS Documentation
+=======================
+
+Pootle FS app provides a plugin framework for synchronizing external
+filesystems containing localisation files.
+
+An FS can be either a local filesystem or a VCS system such as git, svn, hg or
+cvs.
+
+The app uses a configuration syntax to create associations between Pootle
+``Stores`` and file stores. The stores can then be synced and changes in either
+can be tracked.
+
+Syncing is a 2-step process in which changes to Stores/files are initially
+staged with any or all of:
+
+- ``add_translations``
+- ``fetch_translations``
+- ``rm_translations``
+- ``merge_translations``
+
+Changes to previously synced Stores/files are automatically staged for
+synchronisation, where no conflict exists.
+
+Once the desired changes have been staged ``sync_translations`` is called to
+perform the synchronisation.
+
+.. toctree::
+   :maxdepth: 1
+
+   configuration
+   workflow
+   commands
+   status
+   responses
+   plugins/git

docs/plugins/git.rst

@@ -0,0 +1,66 @@
+.. _pootle_fs_git:
+
+Pootle FS Git plugin
+--------------------
+
+Installation
+============
+
+Currently only available for developer install:
+
+`<https://github.com/translate/pootle_fs_git>`_
+
+
+The core pootle_fs app is also required (also dev only):
+
+`<https://github.com/translate/pootle_fs>`_
+
+
+Currently also requires the ``no_mtime`` branch of pootle:
+
+`<https://github.com/phlax/pootle/tree/no_mtime>`_
+
+
+Pootle configuration
+====================
+
+.. code-block:: bash
+
+   (env) $ pootle fs MYPROJECT set_fs git GIT_URL
+
+
+``MYPROJECT`` should be the name of a project in your Pootle site.
+
+``GIT_URL`` should be git ssh url.
+
+
+Git authentication
+==================
+
+Currently only ssh authentication is supported.
+
+The user running the pootle commands therefore must have a working ssh
+environment and read/write access to the git repository in order to synchronize.
+
+
+Custom .pootle.ini options
+==========================
+
+When using the git pootle_fs plugin there are some git-specific options
+
+.. code-block:: bash
+
+   [default]
+   commit_message = "A custom commit message..."
+   author_name = "My Self"
+   author_email = "[email protected]"
+   committer_name = "Pootle Server"
+   committer_email = "[email protected]"
+
+
+Further reading
+===============
+
+- `Workflow <../workflow.rst>`_
+- `Status <../status.rst>`_
+- `Commands <../commands.rst>`_

docs/workflow.rst

@@ -1,22 +1,128 @@
 .. _workflow:
 
-Pootle FS Workflow
-------------------
+Pootle filesystem Workflow
+--------------------------
 
 
+Syncing previously synced Stores/files
+======================================
 
-Pulling translation files from FS to Pootle
-===========================================
+When a ``Store`` and corresponding file have been synced previously, they are
+automatically staged for syncing if either changes.
 
+This is not the case however if both have changed - see resolving conflicts
+section for further information.
 
+To re-sync ``Stores`` and files:
 
-Pushing translation files from Pootle to FS
-===========================================
+.. code-block:: bash
+
+   (env) $ pootle fs myproject sync_translations
+
+
+Pulling new translation files from the filesystem to Pootle
+===========================================================
+
+The workflow for bringing new translations from the filesystem into Pootle is:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject fetch_translations
+   (env) $ pootle fs myproject sync_translations
+
+Where ``fetch_translations`` will stage the new translations, and
+``sync_translations`` will actually sync to the database.
+
+.. note:: You can fetch/sync specific ``Stores`` or files, or groups of them
+	  using the ``-P`` and ``-p`` options to fetch_translations and
+	  sync_translations.
+
+
+Pushing new translation files from Pootle to the filesystem
+===========================================================
+
+The workflow for sending translations from Pootle to the filesystem:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject add_translations
+   (env) $ pootle fs myproject sync_translations
+
+Where ``add_translations`` will stage the new translations, and
+``sync_translations`` will actually sync to the filesystem.
+
+.. note:: You can add/sync specific ``Stores`` or files, or groups of them
+	  using the ``-P`` and ``-p`` options to add_translations and
+	  sync_translations.
 
 
 Resolving conflicts
 ===================
 
+Conflicts can occur if both a Pootle ``Store`` and the corresponding file have
+changed.
+
+Conflict can also arise if a new Pootle ``Store`` is added and a matched file
+has been added in the filesystem.
+
+
+Resolving conflicts - overwriting Pootle with filesystem version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to keep the version that is currently on the filesystem,
+discarding all changes in Pootle, you can do the following:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject fetch_translations --force
+   (env) $ pootle fs myproject sync_translations
+
+
+
+Resolving conflicts - overwriting filesystem with Pootle version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you wish to keep the version that is currently in Pootle,
+discarding all changes in the filesystem, you can do the following:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject add_translations --force
+   (env) $ pootle fs myproject sync_translations
+
+
+Resolving conflicts - merging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to merge the changes made in both Pootle and the filesystem, you can:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject merge_translations
+   (env) $ pootle fs myproject sync_translations
+
+When merging if there are conflicts in translation units the default behaviour
+is to keep the filesystem version, and make the Pootle version into a suggestion.
+
+You can reverse this behaviour as follows:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject merge_translations --pootle-wins
+   (env) $ pootle fs myproject sync_translations
+
 
 Removing files/Stores
-=====================
+^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes a ``Store`` or file is unmatched on the other side, either because it
+is newly added or because a ``Store`` or file has been removed.
+
+You can remove ``Stores`` or files that do not have a corresponding match:
+
+.. code-block:: bash
+   
+   (env) $ pootle fs myproject rm_translations
+   (env) $ pootle fs myproject sync_translations
+
+This will not affect any other ``Stores`` or files.