[PATCH 2 of 4] docs: split vcs_support into admin/vcs_setup and usage/vcs_notes
Thomas De Schampheleire
thomas.de_schampheleire at nokia.com
Mon Jul 30 20:10:10 UTC 2018
# HG changeset patch
# User Thomas De Schampheleire <thomas.de_schampheleire at nokia.com>
# Date 1532807623 -7200
# Sat Jul 28 21:53:43 2018 +0200
# Node ID 64a6161d72e5e5f55924a4cff2a74491faee77fe
# Parent d223d0783942d3d66307b08b48e2de93e244993b
docs: split vcs_support into admin/vcs_setup and usage/vcs_notes
The existing page on VCS support was a mix of information needed to setup
Kallithea with respect to version control systems, with information
regarding using version control systems (or specific aspects of it) with
Kallithea.
Move the first part to the Administrator Guide, and rebrand the second part
as VCS Usage Notes.
In vcs_notes.rst, the general info is moved above the Mercurial-specific
part, but otherwise left untouched.
diff --git a/docs/usage/vcs_support.rst b/docs/administrator_guide/vcs_setup.rst
rename from docs/usage/vcs_support.rst
rename to docs/administrator_guide/vcs_setup.rst
--- a/docs/usage/vcs_support.rst
+++ b/docs/administrator_guide/vcs_setup.rst
@@ -1,14 +1,15 @@
-.. _vcs_support:
+.. _vcs_setup:
===============================
-Version control systems support
+Version control systems setup
===============================
Kallithea supports Git and Mercurial repositories out-of-the-box.
For Git, you do need the ``git`` command line client installed on the server.
You can always disable Git or Mercurial support by editing the
-file ``kallithea/__init__.py`` and commenting out the backend.
+file ``kallithea/__init__.py`` and commenting out the backend. For example, to
+disable Git but keep Mercurial enabled:
.. code-block:: python
@@ -18,8 +19,8 @@ file ``kallithea/__init__.py`` and comme
}
-Git support
------------
+Git-specific setup
+------------------
Web server with chunked encoding
@@ -46,106 +47,6 @@ Also make sure to comment out the follow
use_threadpool =
-Mercurial support
------------------
-
-
-Working with Mercurial subrepositories
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section explains how to use Mercurial subrepositories_ in Kallithea.
-
-Example usage::
-
- ## init a simple repo
- hg init mainrepo
- cd mainrepo
- echo "file" > file
- hg add file
- hg ci --message "initial file"
-
- # clone subrepo we want to add from Kallithea
- hg clone http://kallithea.local/subrepo
-
- ## specify URL to existing repo in Kallithea as subrepository path
- echo "subrepo = http://kallithea.local/subrepo" > .hgsub
- hg add .hgsub
- hg ci --message "added remote subrepo"
-
-In the file list of a clone of ``mainrepo`` you will see a connected
-subrepository at the revision it was cloned with. Clicking on the
-subrepository link sends you to the proper repository in Kallithea.
-
-Cloning ``mainrepo`` will also clone the attached subrepository.
-
-Next we can edit the subrepository data, and push back to Kallithea. This will
-update both repositories.
-
-.. _importing:
-
-
-Importing existing repositories
--------------------------------
-
-There are two main methods to import repositories in Kallithea: via the web
-interface or via the filesystem. If you have a large number of repositories to
-import, importing them via the filesystem is more convenient.
-
-Importing via web interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-For a small number of repositories, it may be easier to create the target
-repositories through the Kallithea web interface, via *Admin > Repositories* or
-via the *Add Repository* button on the entry page of the web interface.
-
-Repositories can be nested in repository groups by first creating the group (via
-*Admin > Repository Groups* or via the *Add Repository Group* button on the
-entry page of the web interface) and then selecting the appropriate group when
-adding the repository.
-
-After creation of the (empty) repository, push the existing commits to the
-*Clone URL* displayed on the repository summary page. For Git repositories,
-first add the *Clone URL* as remote, then push the commits to that remote. The
-specific commands to execute are shown under the *Existing repository?* section
-of the new repository's summary page.
-
-A benefit of this method particular for Git repositories, is that the
-Kallithea-specific Git hooks are installed automatically. For Mercurial, no
-hooks are required anyway.
-
-Importing via the filesystem
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The alternative method of importing repositories consists of creating the
-repositories in the desired hierarchy on the filesystem and letting Kallithea
-scan that location.
-
-All repositories are stored in a central location on the filesystem. This
-location is specified during installation (via ``setup-db``) and can be reviewed
-at *Admin > Settings > VCS > Location of repositories*. Repository groups
-(defined in *Admin > Repository Groups*) are represented by a directory in that
-repository location. Repositories of the repository group are nested under that
-directory.
-
-To import a set of repositories and organize them in a certain repository group
-structure, first place clones in the desired hierarchy at the configured
-repository location.
-These clones should be created without working directory. For Mercurial, this is
-done with ``hg clone -U``, for Git with ``git clone --bare``.
-
-When the repositories are added correctly on the filesystem:
-
-* go to *Admin > Settings > Remap and Rescan* in the Kallithea web interface
-* select the *Install Git hooks* checkbox when importing Git repositories
-* click *Rescan Repositories*
-
-This step will scan the filesystem and create the appropriate repository groups
-and repositories in Kallithea.
-
-*Note*: Once repository groups have been created this way, manage their access
-permissions through the Kallithea web interface.
-
-
.. _waitress: http://pypi.python.org/pypi/waitress
.. _gunicorn: http://pypi.python.org/pypi/gunicorn
.. _subrepositories: http://mercurial.aragost.com/kick-start/en/subrepositories/
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ Administrator guide
:maxdepth: 1
setup
+ administrator_guide/vcs_setup
usage/email
usage/customization
@@ -57,7 +58,7 @@ User guide
:maxdepth: 1
usage/general
- usage/vcs_support
+ usage/vcs_notes
usage/locking
usage/statistics
api/api
diff --git a/docs/usage/vcs_support.rst b/docs/usage/vcs_notes.rst
copy from docs/usage/vcs_support.rst
copy to docs/usage/vcs_notes.rst
--- a/docs/usage/vcs_support.rst
+++ b/docs/usage/vcs_notes.rst
@@ -1,89 +1,11 @@
-.. _vcs_support:
-
-===============================
-Version control systems support
-===============================
-
-Kallithea supports Git and Mercurial repositories out-of-the-box.
-For Git, you do need the ``git`` command line client installed on the server.
-
-You can always disable Git or Mercurial support by editing the
-file ``kallithea/__init__.py`` and commenting out the backend.
-
-.. code-block:: python
-
- BACKENDS = {
- 'hg': 'Mercurial repository',
- #'git': 'Git repository',
- }
-
-
-Git support
------------
-
-
-Web server with chunked encoding
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Large Git pushes require an HTTP server with support for
-chunked encoding for POST. The Python web servers waitress_ and
-gunicorn_ (Linux only) can be used. By default, Kallithea uses
-waitress_ for `gearbox serve` instead of the built-in `paste` WSGI
-server.
-
-The web server used by gearbox is controlled in the .ini file::
-
- use = egg:waitress#main
-
-or::
-
- use = egg:gunicorn#main
+.. _vcs_notes:
-Also make sure to comment out the following options::
-
- threadpool_workers =
- threadpool_max_requests =
- use_threadpool =
-
-
-Mercurial support
------------------
-
-
-Working with Mercurial subrepositories
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section explains how to use Mercurial subrepositories_ in Kallithea.
-
-Example usage::
-
- ## init a simple repo
- hg init mainrepo
- cd mainrepo
- echo "file" > file
- hg add file
- hg ci --message "initial file"
-
- # clone subrepo we want to add from Kallithea
- hg clone http://kallithea.local/subrepo
-
- ## specify URL to existing repo in Kallithea as subrepository path
- echo "subrepo = http://kallithea.local/subrepo" > .hgsub
- hg add .hgsub
- hg ci --message "added remote subrepo"
-
-In the file list of a clone of ``mainrepo`` you will see a connected
-subrepository at the revision it was cloned with. Clicking on the
-subrepository link sends you to the proper repository in Kallithea.
-
-Cloning ``mainrepo`` will also clone the attached subrepository.
-
-Next we can edit the subrepository data, and push back to Kallithea. This will
-update both repositories.
+===================================
+Version control systems usage notes
+===================================
.. _importing:
-
Importing existing repositories
-------------------------------
@@ -145,7 +67,38 @@ and repositories in Kallithea.
*Note*: Once repository groups have been created this way, manage their access
permissions through the Kallithea web interface.
+Mercurial-specific notes
+------------------------
-.. _waitress: http://pypi.python.org/pypi/waitress
-.. _gunicorn: http://pypi.python.org/pypi/gunicorn
+Working with subrepositories
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section explains how to use Mercurial subrepositories_ in Kallithea.
+
+Example usage::
+
+ ## init a simple repo
+ hg init mainrepo
+ cd mainrepo
+ echo "file" > file
+ hg add file
+ hg ci --message "initial file"
+
+ # clone subrepo we want to add from Kallithea
+ hg clone http://kallithea.local/subrepo
+
+ ## specify URL to existing repo in Kallithea as subrepository path
+ echo "subrepo = http://kallithea.local/subrepo" > .hgsub
+ hg add .hgsub
+ hg ci --message "added remote subrepo"
+
+In the file list of a clone of ``mainrepo`` you will see a connected
+subrepository at the revision it was cloned with. Clicking on the
+subrepository link sends you to the proper repository in Kallithea.
+
+Cloning ``mainrepo`` will also clone the attached subrepository.
+
+Next we can edit the subrepository data, and push back to Kallithea. This will
+update both repositories.
+
.. _subrepositories: http://mercurial.aragost.com/kick-start/en/subrepositories/
More information about the kallithea-general
mailing list