From 06e2d9f7caa8bb6a0a8924494387977122533a12 Mon Sep 17 00:00:00 2001 From: Frisk Date: Sat, 15 May 2021 12:58:04 +0200 Subject: [PATCH] Added Util explanation to docs --- docs/API spec.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/API spec.md b/docs/API spec.md index 2d902e7..b0de90a 100644 --- a/docs/API spec.md +++ b/docs/API spec.md @@ -109,7 +109,7 @@ Client consists of the following methods: **Path**: `src.api.context.Context` _Context is a class which objects of are only used as first argument of formatter definitions._ Context can consist of the following fields: -- `client` - Client object +- `client` - [Client](#Client) object - `webhook_url` - string - webhook url for given formatter - `message_type` - string - can be either `embed` or `compact` - `categories` - {"new": set(), "removed": set()} - each set containing strings of added or removed categories for given page @@ -117,5 +117,17 @@ Context can consist of the following fields: - `event` - string - action called, should be the same as formatter event action - `comment_page` - dict - containing `fullUrl` and `article` with strings both to full article url and its name +### Util +**Path**: `src.api.util` +_Util is a module with a few common functions that can be useful for generating Discord messages, parsing changes in formatting and more._ +Util provides the following functionalities: +- `clean_link(link: str)` – returns a string wrapped with <> brackets, so the link given as a string doesn't embed in Discord +- `sanitize_to_markdown(text: str)` – returns a string with Discord Markdown characters escaped +- `sanitize_to_url(text: str)` – returns a string that should be safe to be part of URL with special characters either escaped or encoded +- `parse_mediawiki_changes(ctx: Context, content: str, embed: DiscordMessage)` – populates embed with two new fields "Added" and "Removed" containing diff of changes within content argument retrieved using action=compare request between two revisions +- `create_article_path(article: str)` – returns a string with URL leading to an article page (basically taking into account wiki's article path) +- `compact_author(ctx: Context, content: dict)` – returns two strings - first containing the name of the author with hide_ips setting taken into account and second a URL leading to author's contribution page, this makes it easier for compact formatters to include author detail in messages +- `embed_helper(ctx: Context, message: DiscordMessage, change: dict, set_user=True, set_edit_meta=True, set_desc=True)` – a function populating the message (Discord embed message) with most essential fields accordingly. Populating includes the following fields: author, author_url, category and tags fields, description + ### Language support RcGcDw implements i18n with gettext and already exposes Translations instance with its `src.i18` module. formatters_i18n variable is used for instance of all formatters inside base directory.