From 774d38c3f20b1f31c201926ae7c93ecf8245dd4f Mon Sep 17 00:00:00 2001 From: Blake DeMarcy Date: Wed, 3 May 2017 19:38:07 -0500 Subject: [PATCH] modify the doc script for the new annotations --- document_endpoints.py | 9 +- documentation/docs/api_overview.md | 154 ++++++++++++++++++++++++++++- 2 files changed, 157 insertions(+), 6 deletions(-) diff --git a/document_endpoints.py b/document_endpoints.py index 71d2e31..ac5c874 100644 --- a/document_endpoints.py +++ b/document_endpoints.py @@ -118,7 +118,14 @@ for doctype in sorted(types.keys()): body += "# %s\n\n" % doctype funcs = sorted(types[doctype], key=lambda _: _.__name__) for f in funcs: - body += "## %s\n\n%s\n\n" % (f.__name__, pydoc.getdoc(f)) + body += "## %s\n\n" % f.__name__ + body += "### Args:\n" + for key, value in f.arglist: + if key: + body += "**%s**: %s\n\n" % (key, value) + else: + body += "__No arguments__" + body += "\n\n" + pydoc.getdoc(f) + "\n\n" body += "\n\n--------\n\n" with open("documentation/docs/api_overview.md", "w") as output: diff --git a/documentation/docs/api_overview.md b/documentation/docs/api_overview.md index 3f31e9d..845150a 100644 --- a/documentation/docs/api_overview.md +++ b/documentation/docs/api_overview.md @@ -13,8 +13,8 @@ at the root: `http://server.com/api/endpoint_here` The body of your request contains all of it's argument fields, instead of -using URL parameters. As a demonstration, lets call `thread_create`. -It requires two arguments: `title`, and `body`. We put those argument +using URL parameters. As a demonstration, to call `thread_create`, +it requires two arguments: `title`, and `body`. We put those argument names at the root of the json object, and their values are the info passed into the API for that spot. Your input will look like this: @@ -45,7 +45,7 @@ has three keys: `data`, `usermap`, and `error`. Visualizied: { "error": false, // boolean false or error object "data": null, // null or the requested data from endpoint. - "usermap": {} // a potentially empty object mapping user_ids to their objects + "usermap": {} // potentially empty object, maps user_ids to user objects } // If "error" is true, it looks like this: @@ -79,7 +79,7 @@ ID and profile object as well. ### error -`error` is typically `null`. If it is __not__ null, then the request failed +`error` is typically `false`. If it is __not__ false, then the request failed and the json object that `error` contains should be inspected. (see the above visualation) Errors follow a strict code system, making it easy for your client to map these responses to native exception types or signals in your language of @@ -90,6 +90,13 @@ choice. See [the full error page](errors.md) for details. ## check_auth +### Args: +**target_user**: string: either a user_name or a user_id + +**target_hash**: string: sha256 hash for the password to check + + + Takes the arguments `target_user` and `target_hash`, and returns boolean true or false whether the hash is valid. @@ -101,6 +108,13 @@ returns boolean true or false whether the hash is valid. ## delete_post +### Args: +**thread_id**: string: the id of the thread this message was posted in. + +**post_id**: integer: the id of the target message. + + + Requires the arguments `thread_id` and `post_id`. Delete a message from a thread. The same rules apply @@ -114,6 +128,17 @@ If the post_id is 0, the whole thread is deleted. ## edit_post +### Args: +**thread_id**: string: the thread the message was posted in. + +**post_id**: integer: the target post_id to edit. + +**body**: string: the new message body. + +**OPTIONAL: send_raw**: boolean: set the formatting mode for the target message. + + + Replace a post with a new body. Requires the arguments `thread_id`, `post_id`, and `body`. This method verifies that the user can edit a post before commiting the change, @@ -133,6 +158,13 @@ Returns the new message object. ## edit_query +### Args: +**thread_id**: string: the id of the thread the message was posted in. + +**post_id**: integer: the id of the target message. + + + Queries the database to ensure the user can edit a given message. Requires the arguments `thread_id` and `post_id` (does not require a new body) @@ -142,6 +174,11 @@ on success. Returns a descriptive code 4 otherwise. ## message_feed +### Args: +**time**: int/float: epoch/unix time of the earliest point of interest + + + Returns a special object representing all activity on the board since the argument `time`, a unix/epoch timestamp. @@ -171,6 +208,15 @@ to its documentation for more info. ## set_post_raw +### Args: +**thread_id**: string: the id of the thread the message was posted in. + +**post_id**: integer: the id of the target message. + +**value**: boolean: the new `send_raw` value to apply to the message. + + + Requires the boolean argument of `value`, string argument `thread_id`, and integer argument `post_id`. `value`, when false, means that the message will be passed through message formatters @@ -187,6 +233,13 @@ using this endpoint instead is preferable. ## set_thread_pin +### Args: +**thread_id**: string: the id of the thread to modify. + +**value**: boolean: `true` to pin thread, `false` otherwise. + + + Requires the arguments `thread_id` and `value`. `value` must be a boolean of what the pinned status should be. This method requires that the caller is logged in and @@ -196,6 +249,15 @@ Returns the same boolean you supply as `value` ## thread_create +### Args: +**body**: string: The body of the first message + +**title**: string: The title name for this thread + +**OPTIONAL: send_raw**: boolean: formatting mode for the first message. + + + Creates a new thread and returns it. Requires the non-empty string arguments `body` and `title`. @@ -204,6 +266,11 @@ value, the OP message will never recieve special formatting. ## thread_index +### Args: +**OPTIONAL: include_op**: boolean: Include a `messages` object with the original post + + + Return an array with all the threads, ordered by most recent activity. Requires no arguments. @@ -213,6 +280,15 @@ content is the original message (post_id 0). ## thread_load +### Args: +**thread_id**: string: the thread to load. + +**OPTIONAL: op_only**: boolean: include only the original message in `messages` + +**OPTIONAL: format**: string: the formatting type of the returned messages. + + + Returns the thread object with all of its messages loaded. Requires the argument `thread_id`. `format` may also be specified as a formatter to run the messages through. @@ -223,6 +299,15 @@ is non-nil, the messages array will only include post_id 0 (the first) ## thread_reply +### Args: +**thread_id**: string: the id for the thread this message should post to. + +**body**: string: the message's body of text. + +**OPTIONAL: send_raw**: boolean: formatting mode for the posted message. + + + Creates a new reply for the given thread and returns it. Requires the string arguments `thread_id` and `body` @@ -237,6 +322,15 @@ value, the message will never recieve special formatting. ## db_validate +### Args: +**key**: string: the identifier for the ruleset to check. + +**value**: VARIES: the object for which `key` will check for. + +**OPTIONAL: error**: boolean: when `true`, will return an API error response instead of a special object. + + + Requires the arguments `key` and `value`. Returns an object with information about the database sanity criteria for key. This can be used to validate user input in the client @@ -259,12 +353,22 @@ provided value is safe to use. ## format_message +### Args: +**body**: string: the message body to apply formatting to. + +**format**: string: the specifier for the desired formatting engine + + + Requires the arguments `body` and `format`. Applies `format` to `body` and returns the new object. See `thread_load` for supported specifications for `format`. ## user_map +### Args: +__No arguments__ + Returns an array with all registered user_ids, with the usermap object populated by their full objects. @@ -276,32 +380,72 @@ object populated by their full objects. ## get_me +### Args: +__No arguments__ + Requires no arguments. Returns your internal user object, including your authorization hash. ## is_admin +### Args: +**target_user**: string: user_id or user_name to check against. + + + Requires the argument `target_user`. Returns a boolean of whether that user is an admin. ## user_get -Retreive an external user object for the given `user`. +### Args: +**target_user**: string: either a user_name or a user_id + + + +Retreive an external user object for the given `target_user`. Can be a user_id or user_name. ## user_is_registered +### Args: +**target_user**: string: either a user_name or a user_id + + + Takes the argument `target_user` and returns true or false whether they are in the system or not. ## user_register +### Args: +**user_name**: string: the desired display name + +**auth_hash**: string: a sha256 hash of a password + + + Register a new user into the system and return the new object. Requires the string arguments `user_name` and `auth_hash`. Do not send User/Auth headers with this method. ## user_update +### Args: +**Any of the following may be submitted:**: + +**user_name**: string: a desired display name + +**auth_hash**: string: sha256 hash for a new password + +**quip**: string: a short string that can be used as a signature + +**bio**: string: a user biography for their profile + +**color**: integer: 0-6, a display color for the user + + + Receives new parameters and assigns them to the user_object in the database. The following new parameters can be supplied: `user_name`, `auth_hash`, `quip`, `bio`, and `color`. Any number