added markdown support to airlock requirements and template

opensafely-core · Jan 8, 2025 · ef8147f · ef8147f
1 parent 6f747f1
commit ef8147f
Show file tree

Hide file tree

Showing 63 changed files with 516 additions and 398 deletions.
diff --git a/airlock/settings.py b/airlock/settings.py
@@ -80,6 +80,7 @@ def get_env_var(name):
     "airlock",
     "assets",
     "local_db",  # TODO: not include this application if we're not configured to use it?
+    "markdownify.apps.MarkdownifyConfig",
     # "django.contrib.auth",
     # "django.contrib.contenttypes",
     "django.contrib.sessions",

diff --git a/airlock/templates/file_browser/request/filegroup.html b/airlock/templates/file_browser/request/filegroup.html
@@ -1,3 +1,4 @@
+{% load markdownify %}
 <style>
   .comments .comment_private {
     background-color: lightgrey;
@@ -55,7 +56,7 @@
             </span>
           {% endfragment %}
           {% #list_group_rich_item custom_status=comment_status class=comment_class title=comment.author %}
-            {{ comment.comment }}
+            <div class="prose prose-code:before:hidden prose-code:after:hidden">{{ comment.comment|markdownify }}</div>
             {% if request.user.username == comment.author %}
               {% if comment.visibility.name == "PRIVATE" and comment.review_turn == release_request.review_turn %}
                 <div>
@@ -92,7 +93,7 @@
                 {% /alert %}
               {% endif %}
 
-              {% form_textarea field=group.comment_form.comment placeholder=" " label="Add Comment" show_placeholder=True class="w-full max-w-lg" rows=6 required=False %}
+              {% form_textarea field=group.comment_form.comment placeholder="Use Markdown to format your comment" label="Add Comment" show_placeholder=True class="w-full max-w-lg" rows=6 required=False %}
               {% if group.comment_form.visibility.field.choices|length == 1 %}
                 <input type="hidden" name="visibility" value="{{ group.comment_form.visibility.field.choices.0.0 }}"/>
               {% else %}

diff --git a/docs/how-tos/respond-to-returned-request.md b/docs/how-tos/respond-to-returned-request.md
@@ -18,8 +18,7 @@ file and two files with changes requested:
 ## Comments
 
 Navigate to each of your file groups to view comments from the output checkers. You should add
-comments to respond to any questions or requests for information. Note that your comments will
-not be visible to output checkers until you have submitted the request again for review
+comments to respond to any questions or requests for information. You can [write your comments in markdown](../reference/formatting-comments.md) for additional formatting. Note that your comments will not be visible to output checkers until you have submitted the request again for review
 
 ![Tree for a returned request](../screenshots/returned_request_comments.png)
 

diff --git a/docs/how-tos/review-a-request.md b/docs/how-tos/review-a-request.md
@@ -101,7 +101,7 @@ Comments can be added to each file group, to ask questions, or
 provide information on why changes have been requested to any files.
 
 To add a comment, navigate to the file group by clicking on it in
-the file browser. Enter your comment text and click Save.
+the file browser. Enter your comment text and click Save. You can [write your comments in markdown](../reference/formatting-comments.md) for additional formatting.
 
 ![Comment form](../screenshots/reviewed_request_comment_in_progress.png)
 

diff --git a/docs/reference/formatting-comments.md b/docs/reference/formatting-comments.md
@@ -0,0 +1,45 @@
+Comments can be formatted with markdown using the following supported tags: 
+
+- Anchor: To add a hyperlink. 
+
+Markdown                                            |  Rendered Output
+:-------------------------:                         |:-------------------------:
+![Markdown anchor tag](../screenshots/markdown_comment_anchor_1.png) | ![Rendered anchor tag](../screenshots/markdown_comment_anchor_2.png)
+
+- Bold / Strong
+
+Markdown                                               |  Rendered Output
+:-------------------------:                            |:-------------------------:
+![Markdown bold/strong tag](../screenshots/markdown_comment_bold_1.png) | ![Rendered bold/strong tag](../screenshots/markdown_comment_bold_2.png)
+
+- Block Quote
+
+Markdown                                               |  Rendered Output
+:-------------------------:                            |:-------------------------:
+![Markdown block quote tag](../screenshots/markdown_comment_blockquote_1.png) | ![Rendered block quote tag](../screenshots/markdown_comment_blockquote_2.png)
+
+- Code
+
+Markdown                                               |  Rendered Output
+:-------------------------:                            |:-------------------------:
+![Markdown code tag](../screenshots/markdown_comment_code_1.png) | ![Rendered code tag](../screenshots/markdown_comment_code_2.png)
+
+- Italics
+
+Markdown                                               |  Rendered Output
+:-------------------------:                            |:-------------------------:
+![Markdown italics tag](../screenshots/markdown_comment_italics_1.png) | ![Rendered italics tag](../screenshots/markdown_comment_italics_2.png)
+
+- Ordered lists: The numbers do not need to be in order but must always start with number 1.
+
+Markdown                                               |  Rendered Output
+:-------------------------:                            |:-------------------------:
+![Markdown ordered list tag](../screenshots/markdown_comment_ordered_list_1.png) | ![Rendered ordered list tag](../screenshots/markdown_comment_ordered_list_2.png)
+
+- Unordered lists
+
+Markdown                                               |  Rendered Output
+:-------------------------:                            |:-------------------------:
+![Markdown unordered list tag](../screenshots/markdown_comment_unordered_list_1.png) | ![Rendered unordered list tag](../screenshots/markdown_comment_unordered_list_2.png)
+
+> **Note:**  Abbreviations and acronyms do not have native markdown support.
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -6,3 +6,4 @@ The reference provides background knowledge for working with Airlock.
 * [Viewing underlying source code](view-source-code.md)
 * [Downloading files](downloading-files.md)
 * [Request state diagram](request-states.md)
+* [Formatting comments with markdown](formatting-comments.md)
diff --git a/docs/screenshots/add_file_button.png b/docs/screenshots/add_file_button.png
diff --git a/docs/screenshots/add_file_modal.png b/docs/screenshots/add_file_modal.png
diff --git a/docs/screenshots/context_and_controls.png b/docs/screenshots/context_and_controls.png
diff --git a/docs/screenshots/context_modal.png b/docs/screenshots/context_modal.png
diff --git a/docs/screenshots/file_approved.png b/docs/screenshots/file_approved.png
diff --git a/docs/screenshots/file_group.png b/docs/screenshots/file_group.png
diff --git a/docs/screenshots/file_review.png b/docs/screenshots/file_review.png
diff --git a/docs/screenshots/file_update.png b/docs/screenshots/file_update.png
diff --git a/docs/screenshots/file_update_modal.png b/docs/screenshots/file_update_modal.png
diff --git a/docs/screenshots/files_released.png b/docs/screenshots/files_released.png
diff --git a/docs/screenshots/login_form.png b/docs/screenshots/login_form.png
diff --git a/docs/screenshots/markdown_comment_anchor_1.png b/docs/screenshots/markdown_comment_anchor_1.png
diff --git a/docs/screenshots/markdown_comment_anchor_2.png b/docs/screenshots/markdown_comment_anchor_2.png
diff --git a/docs/screenshots/markdown_comment_blockquote_1.png b/docs/screenshots/markdown_comment_blockquote_1.png
diff --git a/docs/screenshots/markdown_comment_blockquote_2.png b/docs/screenshots/markdown_comment_blockquote_2.png
diff --git a/docs/screenshots/markdown_comment_bold_1.png b/docs/screenshots/markdown_comment_bold_1.png
diff --git a/docs/screenshots/markdown_comment_bold_2.png b/docs/screenshots/markdown_comment_bold_2.png
diff --git a/docs/screenshots/markdown_comment_code_1.png b/docs/screenshots/markdown_comment_code_1.png
diff --git a/docs/screenshots/markdown_comment_code_2.png b/docs/screenshots/markdown_comment_code_2.png
diff --git a/docs/screenshots/markdown_comment_italics_1.png b/docs/screenshots/markdown_comment_italics_1.png
diff --git a/docs/screenshots/markdown_comment_italics_2.png b/docs/screenshots/markdown_comment_italics_2.png
diff --git a/docs/screenshots/markdown_comment_ordered_list_1.png b/docs/screenshots/markdown_comment_ordered_list_1.png
diff --git a/docs/screenshots/markdown_comment_ordered_list_2.png b/docs/screenshots/markdown_comment_ordered_list_2.png
diff --git a/docs/screenshots/markdown_comment_unordered_list_1.png b/docs/screenshots/markdown_comment_unordered_list_1.png
diff --git a/docs/screenshots/markdown_comment_unordered_list_2.png b/docs/screenshots/markdown_comment_unordered_list_2.png
diff --git a/docs/screenshots/more_dropdown.png b/docs/screenshots/more_dropdown.png
diff --git a/docs/screenshots/more_dropdown_el.png b/docs/screenshots/more_dropdown_el.png
diff --git a/docs/screenshots/more_dropdown_el_request_file.png b/docs/screenshots/more_dropdown_el_request_file.png
diff --git a/docs/screenshots/multiselect_update.png b/docs/screenshots/multiselect_update.png
diff --git a/docs/screenshots/ready_to_release.png b/docs/screenshots/ready_to_release.png
diff --git a/docs/screenshots/request_independent_review_file_icons.png b/docs/screenshots/request_independent_review_file_icons.png
diff --git a/docs/screenshots/request_independent_review_researcher_file_icons.png b/docs/screenshots/request_independent_review_researcher_file_icons.png
diff --git a/docs/screenshots/request_overview.png b/docs/screenshots/request_overview.png
diff --git a/docs/screenshots/request_reviewed_file_icons.png b/docs/screenshots/request_reviewed_file_icons.png
diff --git a/docs/screenshots/request_tree.png b/docs/screenshots/request_tree.png
diff --git a/docs/screenshots/request_tree_post_voting.png b/docs/screenshots/request_tree_post_voting.png
diff --git a/docs/screenshots/returned_request_comments.png b/docs/screenshots/returned_request_comments.png
diff --git a/docs/screenshots/returned_tree.png b/docs/screenshots/returned_tree.png
diff --git a/docs/screenshots/reviewed_request_comments.png b/docs/screenshots/reviewed_request_comments.png
diff --git a/docs/screenshots/submit_request.png b/docs/screenshots/submit_request.png
diff --git a/docs/screenshots/submit_review.png b/docs/screenshots/submit_review.png
diff --git a/docs/screenshots/submitted_request.png b/docs/screenshots/submitted_request.png
diff --git a/docs/screenshots/submitted_review.png b/docs/screenshots/submitted_review.png
diff --git a/docs/screenshots/withdraw_request.png b/docs/screenshots/withdraw_request.png
diff --git a/docs/screenshots/withdraw_request_modal.png b/docs/screenshots/withdraw_request_modal.png
diff --git a/docs/screenshots/withdrawn_file.png b/docs/screenshots/withdrawn_file.png
diff --git a/docs/screenshots/workspace_directory_content.png b/docs/screenshots/workspace_directory_content.png
diff --git a/docs/screenshots/workspace_directory_view.png b/docs/screenshots/workspace_directory_view.png
diff --git a/docs/screenshots/workspace_file_icons.png b/docs/screenshots/workspace_file_icons.png
diff --git a/docs/screenshots/workspace_file_view.png b/docs/screenshots/workspace_file_view.png
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -39,6 +39,7 @@ nav:
     - Viewing underlying source code: reference/view-source-code.md
     - Downloading files: reference/downloading-files.md
     - Request state diagram: reference/request-states.md
+    - Formatting comments with markdown: reference/formatting-comments.md
 
 watch:
   - docs