modify the doc script for the new annotations
Blake DeMarcy
parent
2fbd2396aa
commit
774d38c3f2
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue