Improve file diff display in GitHub PR comments (#12918)

Author: ericholscher

readthedocs/builds/tests/test_tasks.py

@@ -352,16 +352,12 @@ def test_post_build_overview(self, get_diff, post_comment):
             [<kbd> &nbsp; 🔍 Preview build &nbsp; </kbd>](http://my-project--1.readthedocs.build/en/1/)
 
 
-            <details>
-            <summary>Show files changed (3 files in total): 📝 1 modified | ➕ 1 added | ➖ 1 deleted</summary>
-
-            | File | Status |
-            | --- | --- |
-            | [changes.html](http://my-project--1.readthedocs.build/en/1/changes.html) | ➕ added |
-            | [deleteme.html](http://my-project--1.readthedocs.build/en/1/deleteme.html) | ➖ deleted |
-            | [index.html](http://my-project--1.readthedocs.build/en/1/index.html) | 📝 modified |
-
-
+            <details open>
+            <summary>3 files changed</summary>
+            <br>
+            <code>+</code> <a href="http://my-project--1.readthedocs.build/en/1/changes.html"><code>changes.html</code></a><br>
+            <code>±</code> <a href="http://my-project--1.readthedocs.build/en/1/index.html"><code>index.html</code></a><br>
+            <code>-</code> <a href="http://my-project--1.readthedocs.build/en/1/deleteme.html"><code>deleteme.html</code></a><br>
             </details>
 
             """
@@ -401,17 +397,20 @@ def test_post_build_overview_more_than_5_files(self, get_diff, post_comment):
 
 
             <details>
-            <summary>Show files changed (6 files in total): 📝 4 modified | ➕ 1 added | ➖ 1 deleted</summary>
+            <summary>6 files changed · <code>+</code> 1 added · <code>±</code> 4 modified · <code>-</code> 1 deleted</summary>
+            <br>
+
+            `+` **Added**
+            - [`changes.html`](http://my-project--1.readthedocs.build/en/1/changes.html)
 
-            | File | Status |
-            | --- | --- |
-            | [changes.html](http://my-project--1.readthedocs.build/en/1/changes.html) | ➕ added |
-            | [deleteme.html](http://my-project--1.readthedocs.build/en/1/deleteme.html) | ➖ deleted |
-            | [index.html](http://my-project--1.readthedocs.build/en/1/index.html) | 📝 modified |
-            | [one.html](http://my-project--1.readthedocs.build/en/1/one.html) | 📝 modified |
-            | [three.html](http://my-project--1.readthedocs.build/en/1/three.html) | 📝 modified |
-            | [two.html](http://my-project--1.readthedocs.build/en/1/two.html) | 📝 modified |
+            `±` **Modified**
+            - [`index.html`](http://my-project--1.readthedocs.build/en/1/index.html)
+            - [`one.html`](http://my-project--1.readthedocs.build/en/1/one.html)
+            - [`three.html`](http://my-project--1.readthedocs.build/en/1/three.html)
+            - [`two.html`](http://my-project--1.readthedocs.build/en/1/two.html)
 
+            `-` **Deleted**
+            - [`deleteme.html`](http://my-project--1.readthedocs.build/en/1/deleteme.html)
 
             </details>
 

readthedocs/filetreediff/dataclasses.py

@@ -175,3 +175,8 @@ def deleted(self):
     def modified(self):
         """List of modified files."""
         return [file for file in self.files if file.status == FileTreeDiffFileStatus.modified]
+
+    @cached_property
+    def should_auto_expand(self):
+        """Auto-expand the details view when there are few files."""
+        return len(self.files) < 5

readthedocs/templates/core/build-overview.md

@@ -3,23 +3,41 @@ Template used for generating the build overview page that is posted as a comment
 
 Whitespaces and newlines are important in some places like lists and tables,
 make sure to adjust the tags accordingly, as they introduce newlines.
+
+Markdown inside <details> requires a blank line after </summary>.
 {% endcomment %}
 ### Documentation build overview
 
 > 📚 [{{ project.name }}](https://{{ PRODUCTION_DOMAIN }}{% url "projects_detail" project.slug %}) | 🛠️ Build [#{{ current_version_build.pk }}](https://{{ PRODUCTION_DOMAIN }}{% url "builds_detail" project.slug current_version_build.pk %}) | 📁 Comparing {{ current_version_build.commit }} against [{{ base_version.verbose_name }}]({{ base_version.get_absolute_url }}) ({{ base_version_build.commit }})
 
 [<kbd> &nbsp; 🔍 Preview build &nbsp; </kbd>]({{ current_version.get_absolute_url }})
 
-{% if diff.files %}
+{% if diff.files %}{% if diff.should_auto_expand %}
+<details open>
+<summary>{{ diff.files|length }} files changed</summary>
+<br>
+{% for file in diff.added %}<code>+</code> <a href="{{ file.url }}"><code>{{ file.path }}</code></a><br>
+{% endfor %}{% for file in diff.modified %}<code>±</code> <a href="{{ file.url }}"><code>{{ file.path }}</code></a><br>
+{% endfor %}{% for file in diff.deleted %}<code>-</code> <a href="{{ file.url }}"><code>{{ file.path }}</code></a><br>
+{% endfor %}</details>
+{% else %}
 <details>
-<summary>Show files changed ({{ diff.files|length }} files in total): 📝 {{ diff.modified|length }} modified | ➕ {{ diff.added|length }} added | ➖ {{ diff.deleted|length }} deleted</summary>
-
-| File | Status |
-| --- | --- |
-{% for file in diff.files %}| [{{ file.path }}]({{ file.url }}) | {{ file.status.emoji }} {{ file.status }} |
-{% endfor %}
-
+<summary>{{ diff.files|length }} files changed{% if diff.added %} · <code>+</code> {{ diff.added|length }} added{% endif %}{% if diff.modified %} · <code>±</code> {{ diff.modified|length }} modified{% endif %}{% if diff.deleted %} · <code>-</code> {{ diff.deleted|length }} deleted{% endif %}</summary>
+<br>
+{% if diff.added %}
+`+` **Added**
+{% for file in diff.added|slice:":10" %}- [`{{ file.path }}`]({{ file.url }})
+{% endfor %}{% if diff.added|length > 10 %}- *and {{ diff.added|length|add:"-10" }} more...*
+{% endif %}{% endif %}{% if diff.modified %}
+`±` **Modified**
+{% for file in diff.modified|slice:":10" %}- [`{{ file.path }}`]({{ file.url }})
+{% endfor %}{% if diff.modified|length > 10 %}- *and {{ diff.modified|length|add:"-10" }} more...*
+{% endif %}{% endif %}{% if diff.deleted %}
+`-` **Deleted**
+{% for file in diff.deleted|slice:":10" %}- [`{{ file.path }}`]({{ file.url }})
+{% endfor %}{% if diff.deleted|length > 10 %}- *and {{ diff.deleted|length|add:"-10" }} more...*
+{% endif %}{% endif %}
 </details>
-{% else %}
+{% endif %}{% else %}
 No files changed.
 {% endif %}