diff --git a/README.rst b/README.rst --- a/README.rst +++ b/README.rst @@ -172,7 +172,7 @@ database: - convert the database in a one-time step Maintaining interoperability -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Interoperability with RhodeCode 2.2.X installations is provided so you don't have to immediately commit to switching to Kallithea. This option will most @@ -191,7 +191,7 @@ then you will find this location at ``$VIRTUAL_ENV/lib/python2.7/site-packages/Kallithea-0.1-py2.7.egg/kallithea``. One-time conversion -~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^ Alternatively, if you would like to convert the database for good, you can use a helper script provided by Kallithea. This script will operate directly on the @@ -209,7 +209,7 @@ database, using the database string you above, watch out for stray brand.pyc after removing brand.py. Git hooks -~~~~~~~~~ +^^^^^^^^^ After switching to Kallithea, it will be necessary to update the Git_ hooks in your repositories. If not, the Git_ hooks from RhodeCode will still be called, diff --git a/docs/api/api.rst b/docs/api/api.rst --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -10,7 +10,7 @@ methods. Everything is available by send API access for web views -++++++++++++++++++++++++ +------------------------ API access can also be turned on for each web view in Kallithea that is decorated with the ``@LoginRequired`` decorator. Some views use @@ -36,7 +36,7 @@ third-party services like code review, o API access -++++++++++ +---------- Clients must send JSON encoded JSON-RPC requests:: @@ -76,7 +76,7 @@ the reponse will have a failure descript API client -++++++++++ +---------- Kallithea comes with a ``kallithea-api`` command line tool, providing a convenient way to call the JSON-RPC API. @@ -110,11 +110,11 @@ so you don't have to specify them every API methods -+++++++++++ +----------- pull ----- +^^^^ Pull the given repo from remote location. Can be used to automatically keep remote repos up to date. @@ -136,7 +136,7 @@ OUTPUT:: error : null rescan_repos ------------- +^^^^^^^^^^^^ Rescan repositories. If ``remove_obsolete`` is set, Kallithea will delete repos that are in the database but not in the filesystem. @@ -159,7 +159,7 @@ OUTPUT:: error : null invalidate_cache ----------------- +^^^^^^^^^^^^^^^^ Invalidate the cache for a repository. This command can only be executed using the api_key of a user with admin rights, @@ -181,7 +181,7 @@ OUTPUT:: error : null lock ----- +^^^^ Set the locking state on the given repository by the given user. If the param ``userid`` is skipped, it is set to the ID of the user who is calling this method. @@ -212,7 +212,7 @@ OUTPUT:: error : null get_ip ------- +^^^^^^ Return IP address as seen from Kallithea server, together with all defined IP addresses for given user. @@ -244,7 +244,7 @@ OUTPUT:: error : null get_user --------- +^^^^^^^^ Get a user by username or userid. The result is empty if user can't be found. If userid param is skipped, it is set to id of user who is calling this method. @@ -288,7 +288,7 @@ OUTPUT:: error: null get_users ---------- +^^^^^^^^^ List all existing users. This command can only be executed using the api_key of a user with admin rights. @@ -325,7 +325,7 @@ OUTPUT:: .. _create-user: create_user ------------ +^^^^^^^^^^^ Create new user. This command can only be executed using the api_key of a user with admin rights. @@ -371,7 +371,7 @@ 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 ------------ +^^^^^^^^^^^ Update the given user if such user exists. This command can only be executed using the api_key of a user with admin rights. @@ -415,7 +415,7 @@ OUTPUT:: error: null delete_user ------------ +^^^^^^^^^^^ Delete the given user if such a user exists. This command can only be executed using the api_key of a user with admin rights. @@ -439,7 +439,7 @@ OUTPUT:: error: null get_user_group --------------- +^^^^^^^^^^^^^^ Get an existing user group. This command can only be executed using the api_key of a user with admin rights. @@ -481,7 +481,7 @@ OUTPUT:: error : null get_user_groups ---------------- +^^^^^^^^^^^^^^^ List all existing user groups. This command can only be executed using the api_key of a user with admin rights. @@ -507,7 +507,7 @@ OUTPUT:: error : null create_user_group ------------------ +^^^^^^^^^^^^^^^^^ Create a new user group. This command can only be executed using the api_key of a user with admin rights. @@ -537,7 +537,7 @@ OUTPUT:: error: null add_user_to_user_group ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ Adds a user to a user group. If the user already is in that group, success will be ``false``. @@ -564,7 +564,7 @@ OUTPUT:: error: null remove_user_from_user_group ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Remove a user from a user group. If the user isn't in the given group, success will be ``false``. @@ -591,7 +591,7 @@ OUTPUT:: error: null get_repo --------- +^^^^^^^^ Get an existing repository by its name or repository_id. Members will contain either users_group or users associated to that repository. @@ -680,7 +680,7 @@ OUTPUT:: error: null get_repos ---------- +^^^^^^^^^ List all existing repositories. This command can only be executed using the api_key of a user with admin rights, @@ -717,7 +717,7 @@ OUTPUT:: error: null get_repo_nodes --------------- +^^^^^^^^^^^^^^ Return a list of files and directories for a given path at the given revision. It is possible to specify ret_type to show only ``files`` or ``dirs``. @@ -748,7 +748,7 @@ OUTPUT:: error: null create_repo ------------ +^^^^^^^^^^^ Create a repository. If the repository name contains "/", all needed repository groups will be created. For example "foo/bar/baz" will create repository groups @@ -800,7 +800,7 @@ OUTPUT:: error: null update_repo ------------ +^^^^^^^^^^^ Update a repository. This command can only be executed using the api_key of a user with admin rights, @@ -860,7 +860,7 @@ OUTPUT:: error: null fork_repo ---------- +^^^^^^^^^ Create a fork of the given repo. If using Celery, this will return success message immediately and a fork will be created @@ -896,7 +896,7 @@ OUTPUT:: error: null delete_repo ------------ +^^^^^^^^^^^ Delete a repository. This command can only be executed using the api_key of a user with admin rights, @@ -923,7 +923,7 @@ OUTPUT:: error: null grant_user_permission ---------------------- +^^^^^^^^^^^^^^^^^^^^^ Grant permission for a user on the given repository, or update the existing one if found. This command can only be executed using the api_key of a user with admin rights. @@ -949,7 +949,7 @@ OUTPUT:: error: null revoke_user_permission ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ Revoke permission for a user on the given repository. This command can only be executed using the api_key of a user with admin rights. @@ -974,7 +974,7 @@ OUTPUT:: error: null grant_user_group_permission ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Grant permission for a user group on the given repository, or update the existing one if found. @@ -1001,7 +1001,7 @@ OUTPUT:: error: null revoke_user_group_permission ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Revoke permission for a user group on the given repository. This command can only be executed using the api_key of a user with admin rights. diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -63,7 +63,7 @@ Kallithea Documentation Other topics ------------- +************ * :ref:`genindex` * :ref:`search` diff --git a/docs/installation_iis.rst b/docs/installation_iis.rst --- a/docs/installation_iis.rst +++ b/docs/installation_iis.rst @@ -28,7 +28,7 @@ will be served from the root of its own own virtual folder will be noted where appropriate. Application pool -................ +^^^^^^^^^^^^^^^^ Make sure that there is a unique application pool for the Kallithea application with an identity that has read access to the Kallithea distribution. @@ -44,7 +44,7 @@ to run on the website and neither will K as long as the Kallithea requirements are met by the existing pool. ISAPI handler -............. +^^^^^^^^^^^^^ The ISAPI handler can be generated using:: @@ -68,7 +68,7 @@ middleware WSGI handler that Kallithea r site will be processed through this logic henceforth. Authentication with Kallithea using IIS authentication modules -.............................................................. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The recommended way to handle authentication with Kallithea using IIS is to let IIS handle all the authentication and just pass it to Kallithea. diff --git a/docs/installation_win.rst b/docs/installation_win.rst --- a/docs/installation_win.rst +++ b/docs/installation_win.rst @@ -6,7 +6,7 @@ Installation and upgrade on Windows (7/S First time install -:::::::::::::::::: +------------------ Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer @@ -15,7 +15,7 @@ Tested on Windows 8.1, Windows Server 20 To install on an older version of Windows, see ``_ Step 1 -- Install Python ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side. @@ -31,7 +31,7 @@ Remember the specific major and minor ve be needed in the next step. In this case, it is "2.7". Step 2 -- Python BIN --------------------- +^^^^^^^^^^^^^^^^^^^^ Add Python BIN folder to the path. This can be done manually (editing "PATH" environment variable) or by using Windows Support Tools that @@ -45,7 +45,7 @@ Please substitute [your-python-path] wit path. Typically this is ``C:\\Python27``. Step 3 -- Install pywin32 extensions ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Download pywin32 from: http://sourceforge.net/projects/pywin32/files/ @@ -61,7 +61,7 @@ http://sourceforge.net/projects/pywin32/ (Win32) Step 4 -- Install pip ---------------------- +^^^^^^^^^^^^^^^^^^^^^ pip is a package management system for Python. You will need it to install Kallithea and its dependencies. @@ -85,7 +85,7 @@ open a CMD and type:: SETX PATH "%PATH%;[your-python-path]\Scripts" /M Step 5 -- Kallithea folder structure ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create a Kallithea folder structure. @@ -102,7 +102,7 @@ Create the following folder structure:: C:\Kallithea\Repos Step 6 -- Install virtualenv ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea. @@ -119,7 +119,7 @@ To create a virtual environment, run:: virtualenv C:\Kallithea\Env Step 7 -- Install Kallithea ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies. Some Python packages use managed code and need to be compiled. @@ -146,7 +146,7 @@ The prompt will change into "(Env) C:\\K normal. Step 8 -- Install git (optional) --------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Mercurial being a python package, it was installed automatically when doing "pip install kallithea". @@ -155,7 +155,7 @@ 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 -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Steps taken from ``_ @@ -194,7 +194,7 @@ 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 ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type:: @@ -222,7 +222,7 @@ What this guide does not cover: Upgrading -::::::::: +--------- Stop running Kallithea Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type:: 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 @@ -6,7 +6,7 @@ Installation and upgrade on Windows (XP/ First-time install -:::::::::::::::::: +------------------ Target OS: Windows XP SP3 32-bit English (Clean installation) + All Windows Updates until 24-may-2012 @@ -24,7 +24,7 @@ Target OS: Windows XP SP3 32-bit English - http://bugs.python.org/issue7511 Step 1 -- Install Visual Studio 2008 Express --------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Optional: You can also install MinGW, but VS2008 installation is easier. @@ -58,7 +58,7 @@ choose "Visual C++ 2008 Express" when in 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 ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Install Python 2.x.y (x = 6 or 7) x86 version (32-bit). DO NOT USE A 3.x version. Download Python 2.x.y from: @@ -74,7 +74,7 @@ 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 ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Download pywin32 from: http://sourceforge.net/projects/pywin32/files/ @@ -93,7 +93,7 @@ http://sourceforge.net/projects/pywin32/ http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download Step 4 -- Python BIN --------------------- +^^^^^^^^^^^^^^^^^^^^ Add Python BIN folder to the path @@ -120,7 +120,7 @@ that came preinstalled in Vista/7 and ca Typically: C:\\Python27 Step 5 -- Kallithea folder structure ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Create a Kallithea folder structure @@ -137,7 +137,7 @@ Create the following folder structure:: C:\Kallithea\Repos Step 6 -- Install virtualenv ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Install Virtual Env for Python @@ -157,7 +157,7 @@ where you downloaded "virtualenv.py", an to include it) Step 7 -- Install Kallithea ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ Finally, install Kallithea @@ -195,7 +195,7 @@ The prompt will change into "(Env) C:\\K Some warnings will appear, don't worry as they are normal. Step 8 -- Configuring Kallithea -------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ steps taken from http://packages.python.org/Kallithea/setup.html @@ -233,7 +233,7 @@ If you make some mistake and the script it again. Step 9 -- Running Kallithea ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the previous command prompt, being in the C:\\Kallithea\\Bin folder, just type:: @@ -263,7 +263,7 @@ What this Guide does not cover: Upgrading -::::::::: +--------- Stop running Kallithea Open a CommandPrompt like in Step7 (VS2008 path + activate) and type:: diff --git a/docs/setup.rst b/docs/setup.rst --- a/docs/setup.rst +++ b/docs/setup.rst @@ -346,7 +346,7 @@ information check out the Kallithea logs will be saved there. Active Directory -'''''''''''''''' +^^^^^^^^^^^^^^^^ Kallithea can use Microsoft Active Directory for user authentication. This is done through an LDAP or LDAPS connection to Active Directory. The @@ -383,7 +383,7 @@ It's also possible for an administrator permissions before the user logs in for the first time, using the :ref:`create-user` API. Container-based authentication -'''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In a container-based authentication setup, Kallithea reads the user name from the ``REMOTE_USER`` server variable provided by the WSGI container. @@ -393,7 +393,7 @@ to configure it to require authenticatio Kallithea. Proxy pass-through authentication -''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In a proxy pass-through authentication setup, Kallithea reads the user name from the ``X-Forwarded-User`` request header, which should be configured to be diff --git a/docs/usage/general.rst b/docs/usage/general.rst --- a/docs/usage/general.rst +++ b/docs/usage/general.rst @@ -151,7 +151,7 @@ described in more detail in this documen features that merit further explanation. Repository extra fields -~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^ In the *Visual* tab, there is an option "Use repository extra fields", which allows to set custom fields for each repository in the system. @@ -165,7 +165,7 @@ about a manager of each repository. The Newly created fields are accessible via the API. Meta tagging -~~~~~~~~~~~~ +^^^^^^^^^^^^ In the *Visual* tab, option "Stylify recognised meta tags" will cause Kallithea to turn certain text fragments in repository and repository group 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 @@ -23,7 +23,7 @@ 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 @@ -51,7 +51,7 @@ Mercurial support Working with Mercurial subrepositories -`````````````````````````````````````` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This section explains how to use Mercurial subrepositories_ in Kallithea. diff --git a/scripts/docs-headings.py b/scripts/docs-headings.py --- a/scripts/docs-headings.py +++ b/scripts/docs-headings.py @@ -15,6 +15,16 @@ spaces = [ (1, 0), ] +# http://sphinx-doc.org/rest.html : +# for the Python documentation, this convention is used which you may follow: +# # with overline, for parts +# * with overline, for chapters +# =, for sections +# -, for subsections +# ^, for subsubsections +# ", for paragraphs +pystyles = ['#', '*', '=', '-', '^', '"'] + # match on a header line underlined with one of the valid characters headermatch = re.compile(r'''\n*(.+)\n([][!"#$%&'()*+,./:;<=>?@\\^_`{|}~-])\2{2,}\n+''', flags=re.MULTILINE) @@ -44,13 +54,16 @@ def main(): # remove superfluous spacing (may however be restored by header spacing) s = re.sub(r'''(\n\n)\n*''', r'\1', s, flags=re.MULTILINE) - # rewrite header markup with correct style, length and spacing - def subf(m): - title, style = m.groups() - level = styles.index(style) - before, after = spaces[level] - return '\n' * (before + 1) + title + '\n' + style * len(title) + '\n' * (after + 1) - s = headermatch.sub(subf, s) + if styles: + newstyles = pystyles[pystyles.index(styles[0]):] + + def subf(m): + title, style = m.groups() + level = styles.index(style) + before, after = spaces[level] + newstyle = newstyles[level] + return '\n' * (before + 1) + title + '\n' + newstyle * len(title) + '\n' * (after + 1) + s = headermatch.sub(subf, s) # remove superfluous spacing when headers are adjacent s = re.sub(r'''(\n.+\n([][!"#$%&'()*+,./:;<=>?@\\^_`{|}~-])\2{2,}\n\n\n)\n*''', r'\1', s, flags=re.MULTILINE)