Some additions to the project import configuration page (#185)

* Some additions to the project import configuration page I pulled down #166 to provide a bit of guidance, but ended up with fixes to the PR either way. I added a few features on top, to replace plain text with visual elements and interactive components. These aren't fully working yet (the example selector namely, see #184). * Update JS comment to be accurate
readthedocs · Jul 11, 2023 · 16b38df · 16b38df
1 parent 6130247
commit 16b38df
Show file tree

Hide file tree

Showing 3 changed files with 64 additions and 25 deletions.
diff --git a/readthedocsext/theme/static/readthedocsext/theme/js/site.js b/readthedocsext/theme/static/readthedocsext/theme/js/site.js
diff --git a/readthedocsext/theme/templates/projects/import_config.html b/readthedocsext/theme/templates/projects/import_config.html
@@ -2,30 +2,60 @@
 {% load i18n %}
 
 {% block project_add_content_subheader %}
-{% trans "Add a configuration file (<code>.readthedocs.yaml</code>) to your project" %}
+  {% trans "Add a configuration file to your project" %}
 {% endblock project_add_content_subheader %}
 
-{% block project_add_css_classes %}ui ten wide tablet wide computer column{% endblock project_add_css_classes %}
-{% block project_add_content_main %}
-<p class="info">
+{% block project_add_content_classes %}ui fourteen wide tablet twelve wide computer column{% endblock %}
+
+{% block project_add_content_form %}
+  <div class="ui small info message">
     {% blocktrans trimmed %}
-    Make sure your project has a <code>.readthedocs.yaml</code> at the root of your repository. This file is required by Read the Docs to be able to build your documentation. You can <a href="https://docs.readthedocs.io/en/stable/config-file/v2.html">read more about this in our documentation</a>.
+      A <code>.readthedocs.yaml</code> configuration file is required at the root of your repository in order to build your documentation.
     {% endblocktrans %}
-</p>
+
+    <a href="https://docs.readthedocs.io/page/config-file/index.html" target="_blank">
+      {% trans "Learn how to add a configuration file to your project." %}
+    </a>
+  </div>
+
+  <div class="ui basic fitted right aligned segment">
+    <span>{% trans "Example configuration for:" %}</span>
+    <div class="ui inline dropdown" data-bind="semanticui: { dropdown: {}}">
+      <input type="hidden" name="tool" value="sphinx">
+      <span class="text">Sphinx</span>
+      <i class="dropdown icon"></i>
+      <div class="menu">
+        <div class="item" data-value="sphinx">Sphinx</div>
+
+        {% comment %}
+          Adding a second option here will require a bit of JS or FUI:
+          https://github.com/readthedocs/ext-theme/issues/184
+        {% endcomment %}
 
-<p class="info">
-    Here you have an example for a common Sphinx project:
+        {# The `actionable` class here prevents the select from selecting the text #}
+        <a class="actionable item" href="https://docs.readthedocs.io/page/config-file/index.html#getting-started-with-a-template" target="_blank">
+          {% trans "See more examples" %}
+        </a>
+      </div>
+    </div>
+  </div>
 
-    <pre class="ui padded">
-        <code class="ui small text">
-# .readthedocs.yaml
+  <div class="ui mini padded inverted scrolling segment">
+    <div class="ui top attached label">
+      <code>.readthedocs.yaml</code>
+    </div>
+    <a class="ui top right attached icon label" href="#" data-clipboard-target="#project-create-sample-sphinx">
+      <i class="fas fa-copy icon"></i>
+    </a>
+    <code class="highlight">
+      <pre id="project-create-sample-sphinx">
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
+# Set the OS, Python version, and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
@@ -50,12 +80,17 @@
 # python:
 #    install:
 #    - requirements: docs/requirements.txt
-        </code>
-    </pre>
-</p>
+      </pre>
+    </code>
+  </div>
+
+  {# Show the base form #}
+  {{ block.super }}
 
-{{ block.super }}
-{% endblock project_add_content_main %}
+{% endblock project_add_content_form %}
 
-{% block project_add_help_topics %}
-{% endblock project_add_help_topics %}
+{% block project_add_sidebar_help_topics %}
+  {% include "includes/elements/link.html" with url="https://docs.readthedocs.io/page/config-file/index.html" text="Configuration file tutorial" is_external=True class="item" %}
+  {% include "includes/elements/link.html" with url="https://docs.readthedocs.io/page/config-file/v2.html" text="Configuration file reference" is_external=True class="item" %}
+  {% include "includes/elements/link.html" with url="https://docs.readthedocs.io/page/guides/setup/git-repo-manual.html" text="Manually configuring a Git repository" is_external=True class="item" %}
+{% endblock project_add_sidebar_help_topics %}
diff --git a/src/js/application/index.js b/src/js/application/index.js
@@ -128,13 +128,17 @@ export class Application {
     });
     jquery(".ui.menu > .item[data-tab]").tab();
 
-    // Initialize clipboard, but only for data-clipboard-text. This is the most
-    // generalized pattern for clipboard usage, so we won't yet worry about
-    // adding the other data binding selectors.
-    var clipboard_global = new clipboard(".ui.button[data-clipboard-text]");
-    jquery(".ui.button[data-clipboard-text]").popup({
+    /* Initialize clipboard.js using a few selectors that we are using. This
+     * isn't a great fit for Knockout custom data binding or plugin, as the
+     * library uses some builtin/hardcoded selectors. */
+    var clipboard_global = new clipboard(
+      "[data-clipboard-text], [data-clipboard-target]"
+    );
+    // Provide the user with some visual feedback using FUI popups
+    jquery("[data-clipboard-text], [data-clipboard-target]").popup({
       on: "click",
       hoverable: false,
+      content: "Copied!",
     });
   }
 }