Add API token instructions to confirmation section

warehouse/static/sass/blocks/_api-token.scss → warehouse/static/sass/blocks/_code-block.scss

@@ -13,14 +13,18 @@
 */
 
 /*
-A custom styled code block for API tokens.
+A custom styled code block.
 
- <code class="api-token">
-   Token here
+ <code class="code-block">
+   Code here
  </code>
+
+ <pre class="code-block">
+   Code here
+ </pre>
 */
 
-.api-token {
+.code-block {
   display: block;
   padding: $spacing-unit / 2;
   margin-bottom: $spacing-unit / 2;

warehouse/static/sass/warehouse.scss

@@ -65,7 +65,6 @@
 // blocks LAYER: some warehouse specific, some generic/reusable
 @import "blocks/about-pypi";
 @import "blocks/accordion";
-@import "blocks/api-token";
 @import "blocks/applied-filters";
 @import "blocks/author-profile";
 @import "blocks/badge";
@@ -75,6 +74,7 @@
 @import "blocks/callout-block";
 @import "blocks/centered-heading";
 @import "blocks/checkbox-tree";
+@import "blocks/code-block";
 @import "blocks/dark-overlay";
 @import "blocks/dropdown";
 @import "blocks/faq-group";

warehouse/templates/manage/token.html

@@ -37,8 +37,7 @@ <h2>Token for "{{ macaroon.description }}"</h2>
       <strong>Scope:</strong> Project "{{ macaroon.caveats.permissions.projects[0] }}"
       {% endif %}
     </p>
-    <p>For instructions on how to use this token, <a href="/help#apitoken">visit the PyPI help page</a>.</p>
-    <code class="api-token">{{ serialized_macaroon }}</code>
+    <code class="code-block">{{ serialized_macaroon }}</code>
     <div class="margin-bottom--large">
       <div class="callout-block callout-block--danger no-top-margin">
         <p>For security reasons this token will only appear once. <strong>Copy it now.</strong></p>
@@ -61,8 +60,40 @@ <h2>Token for "{{ macaroon.description }}"</h2>
 
       {{ confirm_modal(title=title, confirm_name="Username", confirm_string=user.username, confirm_button_label=confirm_button_label, slug=slug, extra_fields=extra_fields, custom_warning_text=token_warning_text, confirm_string_in_title=False) }}
     </div>
-    <hr>
+
+    <h2>Using this token</h2>
+
+    <p>To use this API token:</p>
+
+    <ul>
+      <li>Set your username to <code>__token__</code></li>
+      <li>Set your password to the token value, including the <code>pypi-</code> prefix</li>
+    </ul>
+
+    {% if macaroon.caveats.permissions == "user" %}
+    <p>For example, if you are using <a href="https://pypi.org/project/virtualenv/">Twine</a> to upload your projects to PyPI, set up your <code>$HOME/.pypirc</code> file like this:</p>
+<pre class="code-block">
+[pypi]
+  username = __token__
+  password = {{ serialized_macaroon }}
+</pre>
+    {% else %}
+    <p>For example, if you are using <a href="https://pypi.org/project/virtualenv/">Twine</a> to upload multiple projects to PyPI, you can set up a <code>$HOME/.pypirc</code> file like this:</p>
+<pre class="code-block">
+[pypi]
+  username = __token__
+  password = # either a user-scoped token or a project-scoped token you want to set as the default
+
+[PROJECT_NAME]
+  username = __token__
+  password = # a project token
+</pre>
+    <p>You can then use <code>twine --repository PROJECT_NAME</code> to switch to the correct token when uploading to PyPI.</p>
+    {% endif %}
+
+    <p>For further instructions on how to use this token, <a href="/help#apitoken">visit the PyPI help page</a>.</p>
   </section>
+  <hr>
   {% endif %}
 
   {{ form_error_anchor(create_macaroon_form) }}
@@ -111,7 +142,7 @@ <h2>Add another token</h2>
       </div>
       <div id="api-token-scope-warning" class="callout-block callout-block--warning" hidden>
         <h3 class="callout-block__heading">Proceed with caution!</h3>
-        <p>An API token scoped to your entire account will have upload permissions for all of your projects.</p>
+        <p>An API token scoped to your entire account will have upload permissions for all of your current and future projects.</p>
       </div>
       <div>
         <input value="Add token" class="button button--primary" type="submit">