Mercurial > kallithea
diff docs/usage/general.rst @ 4955:4e6dfdb3fa01
docs: English and consistency corrections
author | Michael V. DePalatis <mike@depalatis.net> |
---|---|
date | Tue, 31 Mar 2015 22:15:38 +0200 |
parents | 03bbd33bc084 |
children | 35d560f0f842 |
line wrap: on
line diff
--- a/docs/usage/general.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/general.rst Tue Mar 31 22:15:38 2015 +0200 @@ -8,48 +8,51 @@ Repository deleting ------------------- -Currently when admin/owner deletes a repository, Kallithea does not physically -delete a repository from filesystem, it renames it in a special way so it's -not possible to push,clone or access repository. It's worth a notice that, -even if someone will be given administrative access to Kallithea and will -delete a repository You can easy restore such action by restoring `rm__<date>` -from the repository name, and internal repository storage (.hg/.git). There -is also a special command for cleaning such archived repos:: +Currently when an admin or owner deletes a repository, Kallithea does +not physically delete said repository from the filesystem, but instead +renames it in a special way so that it is not possible to push, clone +or access repository. It is worth noting that even if someone will be +given administrative access to Kallithea and will delete a repository, +you can easy restore such an action by removing ``rm__<date>`` from +the repository name. There is also a special command for cleaning such +archived repos:: paster cleanup-repos --older-than=30d my.ini -This command will scan for archived repositories that are older than 30d, -display them and ask if you want to delete them (there's a --dont-ask flag also) -If you host big amount of repositories with forks that are constantly deleted -it's recommended that you run such command via crontab. +This command will scan for archived repositories that are older than +30 days, display them, and ask if you want to delete them (there is +a ``--dont-ask`` flag also) If you host a large amount of repositories with +forks that are constantly deleted it is recommended that you run such a +command via crontab. Follow current branch in file view ---------------------------------- In file view when this checkbox is checked the << and >> arrows will jump -to changesets within the same branch currently viewing. So for example -if someone is viewing files at 'beta' branch and marks `follow current branch` -checkbox the << and >> buttons will only show him revisions for 'beta' branch +to changesets within the same branch currently being viewed. So for example +if someone is viewing files in the ``beta`` branch and marks the `follow current branch` +checkbox the << and >> buttons will only show revisions for the `'beta`` branch. Compare view from changelog --------------------------- -Checkboxes in compare view allow users to view combined compare view. You can -only show the range between the first and last checkbox (no cherry pick). -Clicking more than one checkbox will activate a link in top saying -`Show selected changesets <from-rev> -> <to-rev>` clicking this will bring -compare view. In this view also it's possible to switch to combined compare. +Checkboxes in the compare view allow users to view a combined compare +view. You can only show the range between the first and last checkbox +(no cherry pick). Clicking more than one checkbox will activate a +link at the top saying ``Show selected changesets <from-rev> -> +<to-rev>``. Clicking this will activate the compare view. In this view +it is also possible to switch to combined compare. Compare view is also available from the journal on pushes having more than -one changeset +one changeset. Non changeable repository urls ------------------------------ -Due to complicated nature of repository grouping, often urls of repositories -can change. +Due to the complicated nature of repository grouping, URLs of repositories +can often change. example:: @@ -59,58 +62,56 @@ http://server.com/test_group/repo_name This can be an issue for build systems and any other hardcoded scripts, moving -repository to a group leads to a need for changing external systems. To -overcome this Kallithea introduces a non changable replacement url. It's -simply an repository ID prefixed with `_` above urls are also accessible as:: +a repository to a group leads to a need for changing external systems. To +overcome this Kallithea introduces a non-changable replacement URL. It's +simply a repository ID prefixed with ``_``. The above URLs are also accessible as:: http://server.com/_<ID> -Since ID are always the same moving the repository will not affect such url. -the _<ID> syntax can be used anywhere in the system so urls with repo_name -for changelogs, files and other can be exchanged with _<ID> syntax. +Since IDs are always the same, moving the repository will not affect +such a URL. the ``_<ID>`` syntax can be used anywhere in the system so +URLs with ``repo_name`` for changelogs and files can be exchanged +with the ``_<ID>`` syntax. Mailing ------- -When administrator will fill up the mailing settings in .ini files -Kallithea will send mails on user registration, or when Kallithea errors occur -on errors the mails will have a detailed traceback of error. - +When the administrator configures the mailing settings in .ini files +Kallithea will send mails on user registration, or when Kallithea +errors occur. Mails are also sent for code comments. If someone comments on a changeset mail is sent to all participants, the person who commited the changeset -(if present in Kallithea), and to all people mentioned with @mention system. +(if present in Kallithea), and to all people mentioned with the @mention system. Trending source files --------------------- -Trending source files are calculated based on pre defined dict of known -types and extensions. If You miss some extension or Would like to scan some -custom files it's possible to add new types in `LANGUAGES_EXTENSIONS_MAP` dict -located in `/kallithea/lib/celerylib/tasks.py` +Trending source files are calculated based on a pre-defined dict of known +types and extensions. If you miss some extension or would like to scan some +custom files, it is possible to add new types in the ``LANGUAGES_EXTENSIONS_MAP`` dict +located in ``kallithea/lib/celerylib/tasks.py``. Cloning remote repositories --------------------------- -Kallithea has an ability to clone remote repos from given remote locations. -Currently it support following options: +Kallithea has the ability to clone remote repos from given remote locations. +Currently it supports the following options: - hg -> hg clone - svn -> hg clone - git -> git clone -.. note:: - - - *`svn -> hg` cloning requires `hgsubversion` library to be installed.* +.. note:: svn -> hg cloning requires tge ``hgsubversion`` library to be installed. If you need to clone repositories that are protected via basic auth, you -might pass the url with stored credentials inside eg. -`http://user:passw@remote.server/repo`, Kallithea will try to login and clone -using given credentials. Please take a note that they will be stored as +might pass the url with stored credentials inside, e.g., +``http://user:passw@remote.server/repo``, Kallithea will try to login and clone +using the given credentials. Please take note that they will be stored as plaintext inside the database. Kallithea will remove auth info when showing the clone url in summary page. @@ -121,26 +122,28 @@ Visualisation settings in Kallithea settings view are extra customizations -of server behavior. There are 3 main section in the settings. +of server behavior. There are 3 main sections in the settings. General ~~~~~~~ -`Use repository extra fields` option allows to set a custom fields for each -repository in the system. Each new field consists of 3 attributes `field key`, -`field label`, `field description`. Example usage of such fields would be to -define company specific information into repositories eg. defining repo_manager -key that would add give info about a manager of each repository. There's no -limit for adding custom fields. Newly created fields are accessible via API. +The `Use repository extra fields` option allows to set a custom fields +for each repository in the system. Each new field consists of 3 +attributes: ``field key``, ``field label``, ``field +description``. Example usage of such fields would be to define company +specific information into repositories, e.g., defining a +``repo_manager`` key that would give info about a manager of each +repository. There's no limit for adding custom fields. Newly created +fields are accessible via API. -`Show Kallithea version` option toggles displaying exact Kallithea version in -the footer +The `Show Kallithea version` option toggles displaying the exact +Kallithea version in the footer Dashboard items ~~~~~~~~~~~~~~~ -Number if items in main page dashboard before pagination is displayed +Number of items in main page dashboard before pagination is displayed. Icons