Clarify documentation on accessing repositories

Signed-off-by: Michal Čihař <michal@cihar.com>

docs/admin/continuous.rst

@@ -133,7 +133,7 @@ via the admin interface first, otherwise pushing will fail.
    You can also enable automatic pushing changes on commit, this can be done in
    project configuration.
 
-.. seealso:: :ref:`private` for setting up SSH keys
+.. seealso:: :ref:`vcs-repos` for setting up SSH keys
 
 
 .. _github-push:

docs/admin/install.rst

@@ -649,7 +649,7 @@ example to set it to ``configuration`` directory under Weblate tree:
     ``www-data`` or ``wwwrun``, so you either have to run Weblate under
     different user or change this setting.
 
-.. seealso:: :ref:`private`
+.. seealso:: :ref:`vcs-repos`
 
 .. _production-templates:
 

docs/admin/projects.rst

@@ -150,18 +150,14 @@ The component contains all important parameters for working with VCS and
 getting translations out of it:
 
 Source code repository
-    VCS repository used to pull changes.
-
+    VCS repository used to pull changes, see :ref:`vcs-repos` for more details.
+    
     This can be either real VCS URL or ``weblate://project/component``
     indicating that the repository should be shared with another component.
 Repository push URL
     Repository URL used for pushing, this is completely optional and push
-    support will be disabled when this is empty.
-
-    .. note::
-
-        Weblate currently does not support HTTP authentication on push URLs
-
+    support will be disabled when this is empty. See :ref:`vcs-repos` for more
+    details on how to specify repository URL.
 Repository browser
     URL of repository browser to display source files (location where messages
     are used). When empty no such links will be generated.
@@ -352,40 +348,67 @@ it's just a matter of running :djadmin:`import_project`.
 .. seealso:: :ref:`manage`
 
 
+.. _vcs-repos:
+
 Accessing repositories
 ----------------------
 
-.. _private:
+The VCS repository you want to use has to be accessible to Weblate. With
+publicly available repository you just need to enter correct URL (for example
+``git://github.com/nijel/weblate.git`` or
+``https://github.com/nijel/weblate.git``), but for private repositories the
+setup might be more complex.
 
-Private repositories
-++++++++++++++++++++
+SSH repositories
+++++++++++++++++
 
-In case you want Weblate to access private repository it needs to get to it
-somehow. Most frequently used method here is based on SSH. To have access to
-such repository, you generate SSH key for Weblate and authorize it to access
-the repository.
-
-You also need to verify SSH host keys of servers you are going to access.
+Most frequently used method to access private repositories is based on SSH. To
+have access to such repository, you generate SSH key for Weblate and authorize
+it to access the repository.
 
 You can generate or display key currently used by Weblate in the admin
-interface (follow :guilabel:`SSH keys` link on main admin page).
+interface (follow :guilabel:`SSH keys` link on main admin page). Once you've
+done this, Weblate should be able to access your repository.
+
+.. note::
 
-If you are trying to connect to a GitHub repository either use the SSH address
-(eg. ``git@github.com:nijel/weblate.git``)
-or generate personal access token (see `Creating an access token for
-command-line use`_) and include it in the URL. The full URL should look like
+    The keys need to be without password to make it work, so be sure they are
+    well protected against malicious usage.
+
+Before connecting to the repository, you also need to verify SSH host keys of
+servers you are going to access in the same section of the admin interface.
+
+.. note:: 
+   
+    On GitHub, you can add the key to only one repository. See following
+    sections for other solutions for GitHub.
+   
+HTTPS repositories
+++++++++++++++++++
+
+To access protected HTTPS repositories, you need to include user and password
+in the URL. Don't worry, Weblate will strip this information when showing URL
+to the users (if they are allowed to see the repository URL at all).
+
+For example the GitHub URL with authentication might look like 
 ``https://user:your_access_token@github.com/nijel/weblate.git``.
 
-.. _Creating an access token for command-line use: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
+GitHub repositories
++++++++++++++++++++
 
-On GitHub, you can add the key to only one repository. If you plan to access
-more of them, it might be better to create separate user for that, assign him
-Weblate's SSH key and grant him access to all reposities.
+You can access GitHub repositories by SSH as mentioned above, but in case you
+need to access more repositories, you will hit GitHub limitation on the SSH key
+usage (one key can be used only for one repository). There are several ways to
+workaround this limitation. 
 
-.. note::
+For smaller deployments, you can use HTTPS authentication using personal access
+token and your account, see `Creating an access token for command-line use`_.
 
-    The keys need to be without password to make it work, so be sure they are
-    well protected against malicious usage.
+.. _Creating an access token for command-line use: https://help.github.com/articles/creating-an-access-token-for-command-line-use/
+
+For bigger setup, it is usually better to create dedicated user for Weblate,
+assign him the SSH key generated in Weblate and grant him access to all
+repositories you want.
 
 Using proxy
 +++++++++++