Docs: Add separate doc about integration with VCS

It is easier to link and refer to it this way. Also having it
in the "Migrate to Pootle FS" doc could have confused people.

docs/features/index.rst

@@ -14,6 +14,7 @@ Pootle FS
 
    pootle_fs
    migrate_to_pootle_fs
+   integrate_with_vcs
    using_pootle_fs
    pootle_fs_statuses
 

docs/features/integrate_with_vcs.rst

@@ -0,0 +1,98 @@
+.. _integrate_with_vcs:
+
+Integrate with version control system
+=====================================
+
+.. note:: Pootle FS will work out of the box when synchronizing with the local
+   file system. If this is the case you can safely skip the integration with
+   version control.
+
+
+If the translations for your project are stored in a version control system
+(VCS in short), then might be a good idea to directly integrate with the VCS.
+The following instructions work either if you project is already setup to use
+the ``localfs`` Pootle FS backend, or if you are creating and setting a new
+project to directly work with the VCS.
+
+
+.. _integrate_with_vcs#install-vcs-plugins:
+
+Install Pootle FS plugins for VCS
+---------------------------------
+
+Pootle FS provides support for different VCS systems through plugins, so in
+order for Pootle to work with a specific VCS it is necessary to install its
+plugin. For example for Git:
+
+- Install the plugin:
+
+  .. highlight:: console
+  .. parsed-literal::
+
+    (env) $ pip install |--process-dependency-links --pre| Pootle[git]
+
+
+- Add the plugin to :setting:`INSTALLED_APPS` in your custom Pootle settings:
+
+  .. code-block:: python
+
+    INSTALLED_APPS += ['pootle_fs_git']
+
+
+This is done once for the whole Pootle server.
+
+
+.. _integrate_with_vcs#connect-with-vcs:
+
+Connect Pootle FS with VCS repository
+-------------------------------------
+
+The version control system also must provide access for Pootle FS to
+synchronize:
+
+- Create a SSH key:
+
+  .. code-block:: console
+
+    $ sudo -u USER-RUNNING-POOTLE ssh-keygen -b 4096
+
+- Tell your upstream repository about the public key, allowing Pootle to be
+  able to push to the repository. For example for GitHub:
+
+  - Either use the public key as a **Deploy key** for the repository on GitHub,
+  - Or (**preferred**) add the public key to a GitHub user's **SSH and GPG
+    Keys**. In most cases you want to create a specific user in GitHub for
+    Pootle.
+
+
+.. _integrate_with_vcs#configure-project-to-use-vcs:
+
+Configure the project to use VCS
+--------------------------------
+
+After installing the necessary Pootle FS plugin and connecting Pootle FS with
+the VCS repository, it is now necessary to alter the project configuration:
+
+- Deactivate any existing automatic synchronization (like :command:`cron`
+  entries).
+- Disable the project to prevent changes from translators.
+- Ensure you have synchronized all the translation files to disk.
+- Ensure you have committed all the translation files to your version control
+  system.
+- Set the project's **Filesystem backend** to the appropriate VCS backend.
+- Set the URL to your version control repository in the project's **Path or
+  URL**, e.g. ``git@github.com:user/repo.git``.
+- Synchronize as follows:
+
+  .. code-block:: console
+
+    (env) $ pootle fs fetch $MYPROJECT
+    (env) $ pootle fs sync $MYPROJECT
+
+- Enable the project again.
+- Enable automatic synchronization again.
+
+
+Your project is now ready to synchronize with the configured repository using
+Pootle FS. You might want to learn more about how to :ref:`use Pootle FS
+<using_pootle_fs>`.

docs/features/migrate_to_pootle_fs.rst

@@ -73,100 +73,3 @@ commands:
    you must append the ``--pootle-path`` argument for each of command in the
    previous snippet. For example ``--pootle-path=/de/my-project/*`` constrains
    to the project's German database stores.
-
-
-.. _migrate_to_pootle_fs#integrating-with-vcs:
-
-Integrating with version control
---------------------------------
-
-.. note:: Pootle FS will work out of the box when synchronizing with the local
-   file system. If this is the case you can safely skip the integration with
-   version control.
-
-
-With files moved to ``localfs`` it might be a good time to consider directly
-integrating with version control.
-
-
-.. _migrate_to_pootle_fs#install-vcs-plugins:
-
-Install Pootle FS plugins for VCS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Pootle FS provides support for different VCS systems through plugins, so in
-order for Pootle to work with a specific VCS it is necessary to install its
-plugin. For example for Git:
-
-- Install the plugin:
-
-  .. highlight:: console
-  .. parsed-literal::
-
-    (env) $ pip install |--process-dependency-links --pre| Pootle[git]
-
-
-- Add the plugin to :setting:`INSTALLED_APPS` in your custom Pootle settings:
-
-  .. code-block:: python
-
-    INSTALLED_APPS += ['pootle_fs_git']
-
-
-This is done once for the whole Pootle server.
-
-
-.. _migrate_to_pootle_fs#connect-with-vcs:
-
-Connect Pootle FS with VCS repository
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The version control system also must provide access for Pootle FS to
-synchronize:
-
-- Create a SSH key:
-
-  .. code-block:: console
-
-    $ sudo -u USER-RUNNING-POOTLE ssh-keygen -b 4096
-
-- Tell your upstream repository about the public key, allowing Pootle to be
-  able to push to the repository. For example for GitHub:
-
-  - Either use the public key as a **Deploy key** for the repository on GitHub,
-  - Or (**preferred**) add the public key to a GitHub user's **SSH and GPG
-    Keys**. In most cases you want to create a specific user in GitHub for
-    Pootle.
-
-
-.. _migrate_to_pootle_fs#configure-project-to-use-vcs:
-
-Configure the project to use VCS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-After installing the necessary Pootle FS plugin and connecting Pootle FS with
-the VCS repository, it is now necessary to alter the project configuration:
-
-- Deactivate any existing automatic synchronization (like :command:`cron`
-  entries).
-- Disable the project to prevent changes from translators.
-- Ensure you have synchronized all the translation files to disk.
-- Ensure you have committed all the translation files to your version control
-  system.
-- Set the project's **Filesystem backend** to the appropriate VCS backend.
-- Set the URL to your version control repository in the project's **Path or
-  URL**, e.g. ``git@github.com:user/repo.git``.
-- Synchronize as follows:
-
-  .. code-block:: console
-
-    (env) $ pootle fs fetch $MYPROJECT
-    (env) $ pootle fs sync $MYPROJECT
-
-- Enable the project again.
-- Enable automatic synchronization again.
-
-
-Your project is now ready to synchronize with the configured repository using
-Pootle FS. You might want to learn more about how to :ref:`use Pootle FS
-<using_pootle_fs>`.

docs/features/pootle_fs.rst

@@ -96,4 +96,6 @@ out in the long term to make everything use Pootle FS, but you can
 You can find an outline of how to use Pootle FS in the :ref:`using Pootle FS
 <using_pootle_fs>` instructions. If you have a existing project you want to
 migrate to Pootle FS please read the :ref:`migrating your projects to Pootle FS
-<migrate_to_pootle_fs>` instructions.
+<migrate_to_pootle_fs>` instructions. You might also have an already correctly
+setup project that you want to :ref:`integrate directly with a version control
+system <integrate_with_vcs>`.

docs/server/project_setup.rst

@@ -95,9 +95,9 @@ Creating the project
 ++++++++++++++++++++
 
 .. note:: If you want to integrate your project with a version control
-   repository you need to :ref:`install the Pootle FS plugins for the VCS
-   <migrate_to_pootle_fs#install-vcs-plugins>` and :ref:`connect Pootle FS with
-   the VCS repository <migrate_to_pootle_fs#connect-with-vcs>` before creating
+   system you need to :ref:`install the Pootle FS plugins for the VCS
+   <integrate_with_vcs#install-vcs-plugins>` and :ref:`connect Pootle FS with
+   the VCS repository <integrate_with_vcs#connect-with-vcs>` before creating
    the project in Pootle.