# HG changeset patch # User Mads Kiilerich # Date 2015-08-26 15:28:58 # Node ID fbbe80e3322b4ac5e2df7120829eb2f274639d16 # Parent a4c0fe15a6f1ca8766a4520b515200a0611fed5b docs: consistent spacing around headings Start out with 2 empty lines before/after for top level, decrease for deeper levels. diff --git a/README.rst b/README.rst --- a/README.rst +++ b/README.rst @@ -2,6 +2,7 @@ Kallithea README ================ + About ----- @@ -24,6 +25,7 @@ Kallithea was forked from RhodeCode in J Installation ------------ + Kallithea requires Python_ 2.x and it is recommended to install it in a virtualenv_. Official releases of Kallithea can be installed with:: diff --git a/docs/api/api.rst b/docs/api/api.rst --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -4,7 +4,6 @@ API === - Kallithea has a simple JSON RPC API with a single schema for calling all API methods. Everything is available by sending JSON encoded http(s) requests to ``/_admin/api``. @@ -137,7 +136,6 @@ OUTPUT:: result : "Pulled from ``" error : null - rescan_repos ------------ @@ -161,7 +159,6 @@ OUTPUT:: 'removed': []}" error : null - invalidate_cache ---------------- @@ -184,7 +181,6 @@ OUTPUT:: result : "Caches of repository ``" error : null - lock ---- @@ -216,7 +212,6 @@ OUTPUT:: } error : null - get_ip ------ @@ -249,7 +244,6 @@ OUTPUT:: error : null - get_user -------- @@ -295,7 +289,6 @@ OUTPUT:: } error: null - get_users --------- @@ -382,7 +375,6 @@ Example:: kallithea-api create_user username:bent email:bent@example.com firstname:Bent lastname:Bentsen extern_type:ldap extern_name:uid=bent,dc=example,dc=com - update_user ----------- @@ -428,7 +420,6 @@ OUTPUT:: } error: null - delete_user ----------- @@ -454,7 +445,6 @@ OUTPUT:: } error: null - get_user_group -------------- @@ -498,7 +488,6 @@ OUTPUT:: } error : null - get_user_groups --------------- @@ -526,7 +515,6 @@ OUTPUT:: ] error : null - create_user_group ----------------- @@ -558,7 +546,6 @@ OUTPUT:: } error: null - add_user_to_user_group ---------------------- @@ -587,7 +574,6 @@ OUTPUT:: } error: null - remove_user_from_user_group --------------------------- @@ -616,7 +602,6 @@ OUTPUT:: } error: null - get_repo -------- @@ -706,7 +691,6 @@ OUTPUT:: } error: null - get_repos --------- @@ -745,7 +729,6 @@ OUTPUT:: ] error: null - get_repo_nodes -------------- @@ -778,7 +761,6 @@ OUTPUT:: ] error: null - create_repo ----------- @@ -832,7 +814,6 @@ OUTPUT:: } error: null - update_repo ----------- @@ -894,7 +875,6 @@ OUTPUT:: } error: null - fork_repo --------- @@ -932,7 +912,6 @@ OUTPUT:: } error: null - delete_repo ----------- @@ -961,7 +940,6 @@ OUTPUT:: } error: null - grant_user_permission --------------------- @@ -989,7 +967,6 @@ OUTPUT:: } error: null - revoke_user_permission ---------------------- @@ -1016,7 +993,6 @@ OUTPUT:: } error: null - grant_user_group_permission --------------------------- @@ -1045,7 +1021,6 @@ OUTPUT:: } error: null - revoke_user_group_permission ---------------------------- diff --git a/docs/changelog.rst b/docs/changelog.rst --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -6,4 +6,5 @@ Changelog Kallithea project doesn't keep its changelog here. We refer you to our `Mercurial logs`__. + .. __: https://kallithea-scm.org/repos/kallithea/changelog diff --git a/docs/contributing.rst b/docs/contributing.rst --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -24,6 +24,7 @@ than English. Join our project on `Hoste To register, you can use your Bitbucket or GitHub account. See :ref:`translations` for more details. + Getting started --------------- @@ -69,6 +70,7 @@ are:: printed immediately) [NOSE_NOCAPTURE] --failed Run the tests that failed in the last test run. + Coding/contribution guidelines ------------------------------ @@ -134,6 +136,7 @@ elsewhere (for example in a pull request .. _translations: .. include:: ./../kallithea/i18n/how_to + "Roadmap" --------- diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,6 @@ Kallithea Documentation ####################### - **Readme** .. toctree:: @@ -68,6 +67,7 @@ Other topics * :ref:`genindex` * :ref:`search` + .. _virtualenv: http://pypi.python.org/pypi/virtualenv .. _python: http://www.python.org/ .. _django: http://www.djangoproject.com/ diff --git a/docs/installation.rst b/docs/installation.rst --- a/docs/installation.rst +++ b/docs/installation.rst @@ -28,6 +28,7 @@ The following describes three different .. _installation-source: + Installation from repository source ----------------------------------- @@ -48,6 +49,7 @@ server. .. _installation-virtualenv: + Installing a released version in a virtualenv --------------------------------------------- @@ -91,6 +93,7 @@ You can now proceed to :ref:`setup`. .. _installation-without-virtualenv: + Installing a released version without virtualenv ------------------------------------------------ @@ -107,6 +110,7 @@ To install as a regular user in ``~/.loc You can now proceed to :ref:`setup`. + Upgrading Kallithea from Python Package Index (PyPI) ---------------------------------------------------- diff --git a/docs/installation_iis.rst b/docs/installation_iis.rst --- a/docs/installation_iis.rst +++ b/docs/installation_iis.rst @@ -12,12 +12,14 @@ preventing you from applying this on IIS For the best security, it is strongly recommended to only host the site over a secure connection, e.g. using TLS. + Prerequisites ------------- Apart from the normal requirements for Kallithea, it is also necessary to get an ISAPI-WSGI bridge module, e.g. isapi-wsgi. + Installation ------------ @@ -41,7 +43,6 @@ to run on the website and neither will K The application pool can be the same as an existing application pool, as long as the Kallithea requirements are met by the existing pool. - ISAPI handler ............. @@ -89,6 +90,7 @@ external account*. Finally, save the cha The last necessary step is to enable the relevant authentication in IIS, e.g. Windows authentication. + Troubleshooting --------------- diff --git a/docs/installation_win.rst b/docs/installation_win.rst --- a/docs/installation_win.rst +++ b/docs/installation_win.rst @@ -4,6 +4,7 @@ Installation and upgrade on Windows (7/Server 2008 R2 and newer) ================================================================ + First time install :::::::::::::::::: @@ -13,7 +14,6 @@ Tested on Windows 8.1, Windows Server 20 To install on an older version of Windows, see ``_ - Step 1 - Install Python ----------------------- @@ -30,7 +30,6 @@ While writing this guide, the latest ver Remember the specific major and minor versions installed, because they will be needed in the next step. In this case, it is "2.7". - Step 2 - Python BIN ------------------- @@ -45,7 +44,6 @@ Open a CMD and type:: Please substitute [your-python-path] with your Python installation path. Typically this is ``C:\\Python27``. - Step 3 - Install pywin32 extensions ----------------------------------- @@ -62,7 +60,6 @@ http://sourceforge.net/projects/pywin32/ http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download (Win32) - Step 4 - Install pip -------------------- @@ -87,7 +84,6 @@ open a CMD and type:: SETX PATH "%PATH%;[your-python-path]\Scripts" /M - Step 5 - Kallithea folder structure ----------------------------------- @@ -105,7 +101,6 @@ Create the following folder structure:: C:\Kallithea\Env C:\Kallithea\Repos - Step 6 - Install virtualenv --------------------------- @@ -123,7 +118,6 @@ To create a virtual environment, run:: virtualenv C:\Kallithea\Env - Step 7 - Install Kallithea -------------------------- @@ -150,7 +144,6 @@ The prompt will change into "(Env) C:\\K complete. Some warnings will appear. Don't worry, they are normal. - Step 8 - Install git (optional) ------------------------------- @@ -160,7 +153,6 @@ You need to install git manually if you See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions. - Step 9 - Configuring Kallithea ------------------------------ @@ -200,7 +192,6 @@ If you make a mistake and the script doe If you decided not to install git, you will get errors about it that you can ignore. - Step 10 - Running Kallithea --------------------------- diff --git a/docs/installation_win_old.rst b/docs/installation_win_old.rst --- a/docs/installation_win_old.rst +++ b/docs/installation_win_old.rst @@ -4,6 +4,7 @@ Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008) ====================================================================== + First-time install :::::::::::::::::: @@ -24,7 +25,6 @@ Target OS: Windows XP SP3 32-bit English Step 1 - Install Visual Studio 2008 Express ------------------------------------------- - Optional: You can also install MinGW, but VS2008 installation is easier. Download "Visual C++ 2008 Express Edition with SP1" from: @@ -56,7 +56,6 @@ choose "Visual C++ 2008 Express" when in I am not sure why this is not necessary for 32-bit. Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat - Step 2 -- Install Python ------------------------ @@ -73,7 +72,6 @@ be needed in the next step. In this case 64-bit: Just download and install the 64-bit version of python. - Step 3 -- Install Win32py extensions ------------------------------------ @@ -93,7 +91,6 @@ http://sourceforge.net/projects/pywin32/ At the time of writing you can find this at: http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download - Step 4 -- Python BIN -------------------- @@ -121,7 +118,6 @@ that came preinstalled in Vista/7 and ca Please substitute [your-python-path] with your Python installation path. Typically: C:\\Python27 - Step 5 -- Kallithea folder structure ------------------------------------ @@ -139,7 +135,6 @@ Create the following folder structure:: C:\Kallithea\Env C:\Kallithea\Repos - Step 6 -- Install virtualenv ---------------------------- @@ -160,7 +155,6 @@ where you downloaded "virtualenv.py", an (--no-site-packages is now the default behaviour of virtualenv, no need to include it) - Step 7 -- Install Kallithea --------------------------- @@ -199,7 +193,6 @@ The prompt will change into "(Env) C:\\K Some warnings will appear, don't worry as they are normal. - Step 8 -- Configuring Kallithea ------------------------------- @@ -238,11 +231,9 @@ whatever you want) If you make some mistake and the script does not end, don't worry, start it again. - Step 9 -- Running Kallithea --------------------------- - In the previous command prompt, being in the C:\\Kallithea\\Bin folder, just type:: @@ -257,7 +248,6 @@ If it does not work first time, just Ctr again. Don't forget the "http://" in Internet Explorer - What this Guide does not cover: - Installing Celery diff --git a/docs/overview.rst b/docs/overview.rst --- a/docs/overview.rst +++ b/docs/overview.rst @@ -4,7 +4,6 @@ Installation overview ===================== - Some overview and some details that can help understanding the options when installing Kallithea. diff --git a/docs/setup.rst b/docs/setup.rst --- a/docs/setup.rst +++ b/docs/setup.rst @@ -121,6 +121,7 @@ authentication is fully supported. to the Kallithea db and run check functions for permissions against that. + Setting up Whoosh full text search ---------------------------------- @@ -384,7 +385,6 @@ administrator can then modify it using K It's also possible for an administrator to create accounts and configure their permissions before the user logs in for the first time, using the :ref:`create-user` API. - Container-based authentication '''''''''''''''''''''''''''''' @@ -395,7 +395,6 @@ After setting up your container (see `Ap to configure it to require authentication on the location configured for Kallithea. - Proxy pass-through authentication ''''''''''''''''''''''''''''''''' @@ -710,6 +709,7 @@ Add the following at the end of the .ini then change ```` into your chosen prefix + Apache with mod_wsgi -------------------- @@ -807,6 +807,7 @@ the ``init.d`` directory of the Kallithe .. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ . + .. _virtualenv: http://pypi.python.org/pypi/virtualenv .. _python: http://www.python.org/ .. _Mercurial: http://mercurial.selenic.com/ diff --git a/docs/usage/backup.rst b/docs/usage/backup.rst --- a/docs/usage/backup.rst +++ b/docs/usage/backup.rst @@ -10,6 +10,7 @@ Settings Just copy your .ini file, it contains all Kallithea settings. + Whoosh index ------------ diff --git a/docs/usage/debugging.rst b/docs/usage/debugging.rst --- a/docs/usage/debugging.rst +++ b/docs/usage/debugging.rst @@ -9,6 +9,7 @@ on how to debug them. .. note:: First make sure you're using the latest version available. + Enable detailed debug --------------------- diff --git a/docs/usage/email.rst b/docs/usage/email.rst --- a/docs/usage/email.rst +++ b/docs/usage/email.rst @@ -15,6 +15,7 @@ a username (``smtp_username``) and passw port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``) and/or specific authentication parameters (``smtp_auth``). + Application emails ------------------ @@ -42,6 +43,7 @@ a name and an address in the following f optionally be prefixed with the value of ``email_prefix`` in the configuration file. + Error emails ------------ @@ -61,10 +63,12 @@ a name and an address in the following f standard SMTP port (25). If you have a remote SMTP server with a different port, you could set up a local forwarding SMTP server on port 25. + References ---------- - `Error Middleware (Pylons documentation) `_ - `ErrorHandler (Pylons modules documentation) `_ + .. _WebError: https://pypi.python.org/pypi/WebError diff --git a/docs/usage/general.rst b/docs/usage/general.rst --- a/docs/usage/general.rst +++ b/docs/usage/general.rst @@ -27,6 +27,7 @@ It is worth noting that even if someone Kallithea and deletes a repository, you can easily restore such an action by renaming the repository directory, removing the ``rm__`` prefix. + File view: follow current branch -------------------------------- diff --git a/docs/usage/performance.rst b/docs/usage/performance.rst --- a/docs/usage/performance.rst +++ b/docs/usage/performance.rst @@ -54,4 +54,5 @@ 3. Scale Kallithea horizontally that will separate regular user traffic from automated processes like CI servers or build bots. + .. _SQLAlchemyGrate: https://github.com/shazow/sqlalchemygrate diff --git a/docs/usage/vcs_support.rst b/docs/usage/vcs_support.rst --- a/docs/usage/vcs_support.rst +++ b/docs/usage/vcs_support.rst @@ -17,11 +17,14 @@ file ``kallithea/__init__.py`` and comme #'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 @@ -47,8 +50,10 @@ Also make sure to comment out the follow Mercurial support ----------------- + Working with Mercurial subrepositories `````````````````````````````````````` + This section explains how to use Mercurial subrepositories_ in Kallithea. Example usage:: @@ -77,6 +82,7 @@ Cloning ``mainrepo`` will also clone the Next we can edit the subrepository data, and push back to Kallithea. This will update both repositories. + .. _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/kallithea/i18n/how_to b/kallithea/i18n/how_to --- a/kallithea/i18n/how_to +++ b/kallithea/i18n/how_to @@ -9,6 +9,7 @@ Translations are available on Hosted Web Registered users may contribute to the existing languages, or request a new language translations. + Translating using Weblate ------------------------- @@ -26,6 +27,7 @@ them. Most common mistakes are inconsist format parameters, untranslated strings copied into the translation. Please perform necessary corrections when they're needed, or override the false positives. + Merging translations from Weblate --------------------------------- @@ -41,6 +43,7 @@ just the same language translation. That which case it should be manually convinced it has to discard the commits it created by using its administrative interface. + Manual creation of a new language translation --------------------------------------------- @@ -66,6 +69,7 @@ Finally, compile the translations:: python setup.py compile_catalog -l + Updating translations --------------------- @@ -80,6 +84,7 @@ Update the PO file by doing:: Edit the new updated translation file. Repeat all steps after `init_catalog` step from new translation instructions + Testing translations --------------------