docs: update API documentation

docs/api/methods/store-methods.rst

@@ -0,0 +1,37 b''
+.. _store-methods-ref:
+
+store methods
+=============
+
+file_store_add (EE only)
+------------------------
+
+.. py:function:: file_store_add(apiuser, filename, content)
+
+   Upload API for the file_store
+
+   Example usage from CLI::
+       rhodecode-api --instance-name=enterprise-1 upload_file "{"content": "$(cat image.jpg | base64)", "filename":"image.jpg"}"
+
+   This command takes the following options:
+
+   :param apiuser: This is filled automatically from the |authtoken|.
+   :type apiuser: AuthUser
+   :param filename: name of the file uploaded
+   :type filename: str
+   :param content: base64 encoded content of the uploaded file
+   :type content: str
+
+   Example output:
+
+   .. code-block:: bash
+
+     id : <id_given_in_input>
+     result: {
+       "access_path": "/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg",
+       "access_path_fqn": "http://server.domain.com/_file_store/download/84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg",
+       "store_fid": "84d156f7-8323-4ad3-9fce-4a8e88e1deaf-0.jpg"
+     }
+     error :  null
+
+

docs/api/api.rst

@@ -196,7 +196,8 b' are not required in args.'
 .. --- API DEFS MARKER ---
 .. toctree::
 
-   methods/views
+   methods/repo-methods
+   methods/store-methods
    methods/license-methods
    methods/deprecated-methods
    methods/gist-methods

docs/api/methods/pull-request-methods.rst

@@ -83,7 +83,7 b' comment_pull_request'
 create_pull_request 
 -------------------
 
-.. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
+.. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, owner=<Optional:<OptionalAttr:apiuser>>, title=<Optional:''>, description=<Optional:''>, description_renderer=<Optional:''>, reviewers=<Optional:None>)
 
    Creates a new pull request.
 
@@ -104,6 +104,8 b' create_pull_request'
    :type source_ref: str
    :param target_ref: Set the target ref name.
    :type target_ref: str
+   :param owner: user_id or username
+   :type owner: Optional(str)
    :param title: Optionally Set the pull request title, it's generated otherwise
    :type title: str
    :param description: Set the pull request description.
@@ -248,7 +250,7 b' get_pull_request_comments'
 get_pull_requests 
 -----------------
 
-.. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>)
+.. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>, merge_state=<Optional:True>)
 
    Get all pull requests from the repository specified in `repoid`.
 
@@ -262,6 +264,9 b' get_pull_requests'
        * ``open``
        * ``closed``
    :type status: str
+   :param merge_state: Optional calculate merge state for each repository.
+       This could result in longer time to fetch the data
+   :type merge_state: bool
 
    Example output:
 
@@ -356,10 +361,11 b' merge_pull_request'
 
        "id": <id_given_in_input>,
        "result": {
-           "executed":         "<bool>",
-           "failure_reason":   "<int>",
-           "merge_commit_id":  "<merge_commit_id>",
-           "possible":         "<bool>",
+           "executed":               "<bool>",
+           "failure_reason":         "<int>",
+           "merge_status_message":   "<str>",
+           "merge_commit_id":        "<merge_commit_id>",
+           "possible":               "<bool>",
            "merge_ref":        {
                                    "commit_id": "<commit_id>",
                                    "type":      "<type>",

docs/api/methods/repo-methods.rst

@@ -394,15 +394,54 b' get_repo_changesets'
       of changed files.
 
 
-get_repo_nodes 
---------------
+get_repo_comments 
+-----------------
+
+.. py:function:: get_repo_comments(apiuser, repoid, commit_id=<Optional:None>, comment_type=<Optional:None>, userid=<Optional:None>)
+
+   Get all comments for a repository
 
-.. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)
+   :param apiuser: This is filled automatically from the |authtoken|.
+   :type apiuser: AuthUser
+   :param repoid: Set the repository name or repository ID.
+   :type repoid: str or int
+   :param commit_id: Optionally filter the comments by the commit_id
+   :type commit_id: Optional(str), default: None
+   :param comment_type: Optionally filter the comments by the comment_type
+       one of: 'note', 'todo'
+   :type comment_type: Optional(str), default: None
+   :param userid: Optionally filter the comments by the author of comment
+   :type userid: Optional(str or int), Default: None
+
+   Example error output:
+
+   .. code-block:: bash
 
-   Returns a list of nodes and children in a flat list for a given
-   path at given revision.
+       {
+           "id" : <id_given_in_input>,
+           "result" : [
+               {
+                 "comment_author": <USER_DETAILS>,
+                 "comment_created_on": "2017-02-01T14:38:16.309",
+                 "comment_f_path": "file.txt",
+                 "comment_id": 282,
+                 "comment_lineno": "n1",
+                 "comment_resolved_by": null,
+                 "comment_status": [],
+                 "comment_text": "This file needs a header",
+                 "comment_type": "todo"
+               }
+           ],
+           "error" :  null
+       }
 
-   It's possible to specify ret_type to show only `files` or `dirs`.
+
+get_repo_file 
+-------------
+
+.. py:function:: get_repo_file(apiuser, repoid, commit_id, file_path, max_file_bytes=<Optional:None>, details=<Optional:'basic'>, cache=<Optional:True>)
+
+   Returns a single file from repository at given revision.
 
    This command can only be run using an |authtoken| with admin rights,
    or users with at least read rights to |repos|.
@@ -411,37 +450,104 b' get_repo_nodes'
    :type apiuser: AuthUser
    :param repoid: The repository name or repository ID.
    :type repoid: str or int
-   :param revision: The revision for which listing should be done.
-   :type revision: str
-   :param root_path: The path from which to start displaying.
-   :type root_path: str
-   :param ret_type: Set the return type. Valid options are
-       ``all`` (default), ``files`` and ``dirs``.
-   :type ret_type: Optional(str)
-   :param details: Returns extended information about nodes, such as
-       md5, binary, and or content.  The valid options are ``basic`` and
-       ``full``.
+   :param commit_id: The revision for which listing should be done.
+   :type commit_id: str
+   :param file_path: The path from which to start displaying.
+   :type file_path: str
+   :param details: Returns different set of information about nodes.
+       The valid options are ``minimal`` ``basic`` and ``full``.
    :type details: Optional(str)
    :param max_file_bytes: Only return file content under this file size bytes
-   :type details: Optional(int)
-
+   :type max_file_bytes: Optional(int)
+   :param cache: Use internal caches for fetching files. If disabled fetching
+       files is slower but more memory efficient
+   :type cache: Optional(bool)
    Example output:
 
    .. code-block:: bash
 
        id : <id_given_in_input>
-       result: [
-                 {
-                   "name" : "<name>"
-                   "type" : "<type>",
-                   "binary": "<true|false>" (only in extended mode)
-                   "md5"  : "<md5 of file content>" (only in extended mode)
-                 },
-                 ...
-               ]
+       result: {
+           "binary": false,
+           "extension": "py",
+           "lines": 35,
+           "content": "....",
+           "md5": "76318336366b0f17ee249e11b0c99c41",
+           "mimetype": "text/x-python",
+           "name": "python.py",
+           "size": 817,
+           "type": "file",
+       }
        error:  null
 
 
+get_repo_fts_tree 
+-----------------
+
+.. py:function:: get_repo_fts_tree(apiuser, repoid, commit_id, root_path)
+
+   Returns a list of tree nodes for path at given revision. This api is built
+   strictly for usage in full text search building, and shouldn't be consumed
+
+   This command can only be run using an |authtoken| with admin rights,
+   or users with at least read rights to |repos|.
+
+
+get_repo_nodes 
+--------------
+
+.. py:function:: get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>, max_file_bytes=<Optional:None>)
+
+   Returns a list of nodes and children in a flat list for a given
+       path at given revision.
+
+       It's possible to specify ret_type to show only `files` or `dirs`.
+
+       This command can only be run using an |authtoken| with admin rights,
+       or users with at least read rights to |repos|.
+
+       :param apiuser: This is filled automatically from the |authtoken|.
+       :type apiuser: AuthUser
+       :param repoid: The repository name or repository ID.
+       :type repoid: str or int
+       :param revision: The revision for which listing should be done.
+       :type revision: str
+       :param root_path: The path from which to start displaying.
+       :type root_path: str
+       :param ret_type: Set the return type. Valid options are
+           ``all`` (default), ``files`` and ``dirs``.
+       :type ret_type: Optional(str)
+       :param details: Returns extended information about nodes, such as
+           md5, binary, and or content.
+           The valid options are ``basic`` and ``full``.
+       :type details: Optional(str)
+       :param max_file_bytes: Only return file content under this file size bytes
+       :type details: Optional(int)
+
+       Example output:
+
+       .. code-block:: bash
+
+           id : <id_given_in_input>
+           result: [
+                       {
+                         "binary": false,
+                         "content": "File line
+   Line2
+   ",
+                         "extension": "md",
+                         "lines": 2,
+                         "md5": "059fa5d29b19c0657e384749480f6422",
+                         "mimetype": "text/x-minidsrc",
+                         "name": "file.md",
+                         "size": 580,
+                         "type": "file"
+                       },
+                     ...
+                   ]
+           error:  null
+
+
 get_repo_refs 
 -------------
 

docs/api/methods/server-methods.rst

@@ -103,7 +103,7 b' get_method'
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param pattern: pattern to match method names against
-   :type older_then: Optional("*")
+   :type pattern: Optional("*")
 
    Example output:
 
@@ -232,3 +232,37 b' rescan_repos'
      }
 
 
+store_exception 
+---------------
+
+.. py:function:: store_exception(apiuser, exc_data_json, prefix=<Optional:'rhodecode'>)
+
+   Stores sent exception inside the built-in exception tracker in |RCE| server.
+
+   This command can only be run using an |authtoken| with admin rights to
+   the specified repository.
+
+   This command takes the following options:
+
+   :param apiuser: This is filled automatically from the |authtoken|.
+   :type apiuser: AuthUser
+
+   :param exc_data_json: JSON data with exception e.g
+       {"exc_traceback": "Value `1` is not allowed", "exc_type_name": "ValueError"}
+   :type exc_data_json: JSON data
+
+   :param prefix: prefix for error type, e.g 'rhodecode', 'vcsserver', 'rhodecode-tools'
+   :type prefix: Optional("rhodecode")
+
+   Example output:
+
+   .. code-block:: bash
+
+     id : <id_given_in_input>
+     "result": {
+       "exc_id": 139718459226384,
+       "exc_url": "http://localhost:8080/_admin/settings/exceptions/139718459226384"
+     }
+     error :  null
+
+