From dec9a053cc99851f9d2223cb03d5129a5fea9f85 Mon Sep 17 00:00:00 2001 From: Hannes Janott Date: Mon, 25 Nov 2024 14:56:05 +0100 Subject: [PATCH] beautify presenter docs (#2732) Improving js syntax Adding js highlighting Deleting deleted presenters Specifying required and optional parameters --- docs/migration_route.md | 4 +-- docs/presenters/check_database.md | 12 +++---- docs/presenters/check_database_all.md | 10 +++--- docs/presenters/export_meeting.md | 4 +-- docs/presenters/get_active_users_amount.md | 2 +- docs/presenters/get_forwarding_committees.md | 6 ++-- docs/presenters/get_forwarding_meetings.md | 12 +++---- docs/presenters/get_mediafile_context.md | 18 +++++----- docs/presenters/get_meetings.md | 28 --------------- docs/presenters/get_user_related_models.md | 20 +++++------ docs/presenters/get_user_scope.md | 4 +-- docs/presenters/get_users.md | 11 +++--- docs/presenters/search_deleted_models.md | 36 ------------------- .../search_for_id_by_external_id.md | 12 +++---- docs/presenters/search_users.md | 5 +-- 15 files changed, 61 insertions(+), 123 deletions(-) delete mode 100644 docs/presenters/get_meetings.md delete mode 100644 docs/presenters/search_deleted_models.md diff --git a/docs/migration_route.md b/docs/migration_route.md index 26bd427f6..8a80883d2 100644 --- a/docs/migration_route.md +++ b/docs/migration_route.md @@ -23,7 +23,7 @@ enum MigrationState { "success": true, "status"?: MigrationState, "output"?: str, - "exception"?: str, + "exception"?: str } ``` `output` always contains the full output of the migration command up to this point. `exception` contains the thrown exception, if any, which can only be the case if the command is finished (meaning `status != "migration_running"`). After issuing a migration command, it is waited a short period of time for the thread to finish, so the status can be all of these things for any command (e.g. after calling `migrate`, the returned status can be either `MIGRATION_RUNNING` if the migrations did not finish directly or `FINALIZATION_REQUIRED` if the migration is already done). @@ -41,7 +41,7 @@ The `stats` return value is the following: "positions": int, "events": int, "partially_migrated_positions": int, - "fully_migrated_positions": int, + "fully_migrated_positions": int } } ``` diff --git a/docs/presenters/check_database.md b/docs/presenters/check_database.md index 57518ec93..cf1574bf8 100644 --- a/docs/presenters/check_database.md +++ b/docs/presenters/check_database.md @@ -1,23 +1,23 @@ # Payload -``` +```js { // optional - meeting_id: integer; + meeting_id: integer } ``` # Returns If okay: -``` +```js { - ok: boolean, + ok: boolean } ``` else: -``` +```js { ok: boolean, - errors: string, + errors: string } ``` diff --git a/docs/presenters/check_database_all.md b/docs/presenters/check_database_all.md index 393c25ae7..e2881c5ba 100644 --- a/docs/presenters/check_database_all.md +++ b/docs/presenters/check_database_all.md @@ -1,21 +1,21 @@ # Payload -``` +```js { } ``` # Returns If okay: -``` +```js { - ok: boolean, + ok: boolean } ``` else: -``` +```js { ok: boolean, - errors: string, + errors: string } ``` diff --git a/docs/presenters/export_meeting.md b/docs/presenters/export_meeting.md index 02d73abc1..b94aaab65 100644 --- a/docs/presenters/export_meeting.md +++ b/docs/presenters/export_meeting.md @@ -1,8 +1,8 @@ # Payload -``` +```js { - meeting_id: Id + meeting_id: Id // required } ``` diff --git a/docs/presenters/get_active_users_amount.md b/docs/presenters/get_active_users_amount.md index 018973a64..5e6ce7a14 100644 --- a/docs/presenters/get_active_users_amount.md +++ b/docs/presenters/get_active_users_amount.md @@ -6,7 +6,7 @@ Nothing ```js { - active_users_amount: Number; + active_users_amount: Number } ``` diff --git a/docs/presenters/get_forwarding_committees.md b/docs/presenters/get_forwarding_committees.md index df01a6943..afc410ec4 100644 --- a/docs/presenters/get_forwarding_committees.md +++ b/docs/presenters/get_forwarding_committees.md @@ -1,14 +1,14 @@ # Payload -``` +```js { - meeting_id: Id + meeting_id: Id // required } ``` # Returns -``` +```js string[] ``` diff --git a/docs/presenters/get_forwarding_meetings.md b/docs/presenters/get_forwarding_meetings.md index b76a5c454..d97135601 100644 --- a/docs/presenters/get_forwarding_meetings.md +++ b/docs/presenters/get_forwarding_meetings.md @@ -1,19 +1,19 @@ # Payload -``` +```js { - meeting_id: Id + meeting_id: Id // required } ``` # Returns -``` +```js [ { - id: Id - name: string - default_meeting_id: Id + id: Id, + name: string, + default_meeting_id: Id, meeting: [{id: Id, name: string, start_time:timestamp|null, end_time:timestamp|null}, ...] }, ... diff --git a/docs/presenters/get_mediafile_context.md b/docs/presenters/get_mediafile_context.md index e67fb8192..cd91e4352 100644 --- a/docs/presenters/get_mediafile_context.md +++ b/docs/presenters/get_mediafile_context.md @@ -2,7 +2,7 @@ ```js { - mediafile_ids: Id[]; + mediafile_ids: Id[] // required } ``` @@ -15,16 +15,16 @@ published: boolean, meetings_of_interest: { [meeting_id: Id]: { - name: string; - holds_attachments: boolean; - holds_logos: boolean; - holds_fonts: boolean; - holds_current_projections: boolean; - holds_history_projections: boolean; - holds_preview_projections: boolean; + name: string, + holds_attachments: boolean, + holds_logos: boolean, + holds_fonts: boolean, + holds_current_projections: boolean, + holds_history_projections: boolean, + holds_preview_projections: boolean } }, - children_amount: int, + children_amount: int } } ``` diff --git a/docs/presenters/get_meetings.md b/docs/presenters/get_meetings.md deleted file mode 100644 index 00567e7c3..000000000 --- a/docs/presenters/get_meetings.md +++ /dev/null @@ -1,28 +0,0 @@ -# Payload - -``` -{ - with_deleted: boolean, # default: False - with_archived: boolean, # default: False -} -``` - -# Returns - -``` -[ - { - id: Id, - name: string, - deleted: boolean, - is_active_in_organization: int, - }, - ... -] -``` - -# Logic - -The request user needs OML `can_manage_users` or higher or CML `can_manage`. - -This presenter creates a filtered list of meetings for various situations. With CML permission the list shows only meetings of committees, where the user has the needed permission. diff --git a/docs/presenters/get_user_related_models.md b/docs/presenters/get_user_related_models.md index db71df47f..6f7a9808d 100644 --- a/docs/presenters/get_user_related_models.md +++ b/docs/presenters/get_user_related_models.md @@ -2,7 +2,7 @@ ```js { - user_ids: Id[]; + user_ids: Id[] // required } ``` @@ -12,16 +12,16 @@ { [user_id: Id]: { organization_management_level: OML-String, - committees: [{ id: Id; name: String; cml: CML-String; }], + committees: [{ id: Id, name: String, cml: CML-String }], meetings: [{ - id: Id; - name: String; - is_active_in_organization_id: Id; - is_locked: boolean; - motion_submitter_ids: Id[]; - assignment_candidate_ids: Id[]; - speaker_ids: Id[]; - locked_out: boolean; + id: Id, + name: String, + is_active_in_organization_id: Id, + is_locked: boolean, + motion_submitter_ids: Id[], + assignment_candidate_ids: Id[], + speaker_ids: Id[], + locked_out: boolean }] } } diff --git a/docs/presenters/get_user_scope.md b/docs/presenters/get_user_scope.md index 928d8fc25..b4b4eca3a 100644 --- a/docs/presenters/get_user_scope.md +++ b/docs/presenters/get_user_scope.md @@ -2,7 +2,7 @@ ```js { - user_ids: Id[]; + user_ids: Id[] // required } ``` @@ -13,7 +13,7 @@ user_id: Id: { collection: String, # one of "meeting", "committee" or "organization" id: Id, - user_oml: String, # one of "superadmin", "can_manage_organization", "can_manage_users", "" + user_oml: String, # one of "superadmin", "can_manage_organization", "can_manage_users", "" committee_ids: int[] // Ids of all committees the user is part of } } diff --git a/docs/presenters/get_users.md b/docs/presenters/get_users.md index b20707f5f..65b147a66 100644 --- a/docs/presenters/get_users.md +++ b/docs/presenters/get_users.md @@ -1,24 +1,25 @@ # Payload -``` +```js { + // optional start_index: number, entries: number, sort_criteria: string[], // can contain ["username", "first_name", "last_name"], reverse: boolean, - filter?: string, + filter?: string } ``` # Returns -``` +```js [ { id: Id, username: string, first_name: string, - last_name: string, + last_name: string }, ... ] @@ -28,4 +29,4 @@ The request user needs OML `can_manage_users` or higher. Otherwise an error is returned. -Returns all users, that have `filer` in `username`, `first_name`, `last_name`. If filter is `null`, all users are returned. The users are sorted by `sort_criteria`. If it is not given, the default is `["username", "first_name", "last_name"]`. If `reverse` is true, the order is reversed. Lastly, the users are paginated beginning at `start_index` with at max `entries` number of users. +Returns all users, that have `filter` in `username`, `first_name`, `last_name`. If filter is `null`, all users are returned. The users are sorted by `sort_criteria`. If it is not given, the default is `["username", "first_name", "last_name"]`. If `reverse` is true, the order is reversed. Lastly, the users can be paginated beginning at `start_index` with at max `entries` number of users. diff --git a/docs/presenters/search_deleted_models.md b/docs/presenters/search_deleted_models.md deleted file mode 100644 index 3abb15b10..000000000 --- a/docs/presenters/search_deleted_models.md +++ /dev/null @@ -1,36 +0,0 @@ -## Payload - -```js -{ - collection: string, - filter_string: string, - meeting_id: Id, -} -``` - -## Presenter - -Searches all deleted models of the given collection in the given meeting for the given filter string. The fields which -are searched differ from collection to collection: -``` -{ - "assignment": ["title"], - "motion": ["number", "title"], - "user": [ - "username", - "first_name", - "last_name", - "title", - "pronoun", - "structure_level", - "number", - "email", - ], -} -``` -These 3 are also the only allowed collections. The result list is returned as a mapping from the -model's id to the searched fields of the model (see above). - -## Permissions - -TODO diff --git a/docs/presenters/search_for_id_by_external_id.md b/docs/presenters/search_for_id_by_external_id.md index ebbd42a81..b90145c89 100644 --- a/docs/presenters/search_for_id_by_external_id.md +++ b/docs/presenters/search_for_id_by_external_id.md @@ -2,22 +2,22 @@ ```js { // required - collection: string; - external_id: string; - context_id: Id; + collection: string, + external_id: string, + context_id: Id } ``` ## Returns ```js { - id: Id; + id: Id } ``` in the case one id is found. ```js { - id: null; - error: string; + id: null, + error: string } ``` else. diff --git a/docs/presenters/search_users.md b/docs/presenters/search_users.md index 416cafead..a22007587 100644 --- a/docs/presenters/search_users.md +++ b/docs/presenters/search_users.md @@ -2,6 +2,7 @@ ```js { + // required permission_type: "meeting" | "committee" | "organization" permission_id: number, // Id of permission scope object search: { @@ -10,7 +11,7 @@ "first_name": string, "last_name": string, "email": string, - "member_number": string, + "member_number": string }[] } ``` @@ -24,7 +25,7 @@ "first_name": string, "last_name": string, "email": string, - "member_number": string, + "member_number": string }[][] ``` A double array: The outer array has the same length as the request's `search` array and contains