Simplify the /files documentation

Remove most of the documentation in favor of a link to a new page on rsp.lsst.io. Display the WebDAV file server timeout in a more human-readable form.
lsst-sqre · Jul 5, 2024 · 128e456 · 128e456
1 parent 4f7849f
commit 128e456
Show file tree

Hide file tree

Showing 4 changed files with 71 additions and 131 deletions.
diff --git a/changelog.d/20240220_163206_rra_DM_42930.md b/changelog.d/20240220_163206_rra_DM_42930.md
@@ -0,0 +1,7 @@
+### Bug fixes
+
+- Display the timeout in the `/files` documentation in a more human-readable format.
+
+### Other changes
+
+- Remove most of the `/files` documentation in favor of a link to [rsp.lsst.io](https://rsp.lsst.io/guides/notebooks/extfileaccess/webdav/).
diff --git a/controller/src/controller/templates.py b/controller/src/controller/templates.py
@@ -33,23 +33,28 @@ def _format_timedelta(delta: timedelta) -> str:
     Returns
     -------
     str
-        Human-readable equivalent using ``d`` for days, ``h`` for hours, ``m``
-        for minutes, and ``s`` for seconds. Daylight saving time transitions
-        are not taken into account.
+        Human-readable equivalent. Daylight saving time transitions are not
+        taken into account.
     """
     seconds = int(delta.total_seconds())
     days, seconds = divmod(seconds, 86400)
     hours, seconds = divmod(seconds, 3600)
     minutes, seconds = divmod(seconds, 60)
     string = ""
     if days:
-        string = f"{days}d"
+        string = f"{days} " + ("day" if days == 1 else "days")
     if hours:
-        string += f"{hours}h"
+        if string:
+            string += " "
+        string += f"{hours} " + ("hour" if hours == 1 else "hours")
     if minutes:
-        string += f"{minutes}m"
+        if string:
+            string += " "
+        string += f"{minutes} " + ("minute" if minutes == 1 else "minutes")
     if seconds:
-        string += f"{seconds}s"
+        if string:
+            string += " "
+        string += f"{seconds} " + ("second" if seconds == 1 else "seconds")
     return string
 
 

diff --git a/controller/src/controller/templates/fileserver.html.jinja b/controller/src/controller/templates/fileserver.html.jinja
@@ -1,64 +1,28 @@
 <html>
-<head>
-<title>
-User Fileserver Created
-</title>
-</head>
-</body>
-<h1>
-Your fileserver is ready.
-<h1>
-
-<h2>
-Access Token
-</h2>
-
-<p> If you do not have an access token, go to <a
-href="{{ base_url }}/auth/tokens">the Gafaelfawr tokens page</a> and press
-the "Create Token" button.  </p>
-
-<p>
-Give that token a name, such as "fileserver", the "exec:notebook" scope,
-and a reasonable expiration duration, such as 1 month.
-</p>
-
-<p>
-Press "Create".
-</p>
-
-<p>
-Your token will be displayed.  Copy this token and save it somewhere
-safe; you will never be able to view it from the tokens page again.
-</p>
-
-<h2>
-Using the Fileserver
-</h2>
-
-<p>
-To use the fileserver, you will need a WebDAV client of your choice.
-Mac and Windows have built-in WebDAV clients (this is "Connect to
-Server..." or "Map Network Drive..."), as do Gnome Nautilus and
-Konqueror for Linux.  The open-source command-line client
-<a href="https://github.com/notroj/cadaver">cadaver</a> should build on
-almost any Unix-like system and will work.
-</p>
-
-<p>
-Connect to
-<a href="{{ base_url }}{{ path_prefix }}/{{ username }}">{{ base_url }}{{ path_prefix }}/{{ username }}</a>
-with your WebDAV client (for Konqueror, use "webdav" or "webdavs" rather
-than "http" or "https" as the protocol).  Use the token you acquired
-earlier as the password.  You can use any string for your username
-(since the token belongs to you, it identifies you), but "{{ username }}"
-would be both accurate and traditional.
-</p>
-
-<p>
-If you make no requests in {{ timeout | format_timedelta }}, the fileserver will shut
-down.  If that occurs, simply go back to
-<a href="{{ base_url }}{{ path_prefix }}">{{ base_url }}{{ path_prefix }}</a>
-and a new fileserver will be created for you.
-</p>
-</body>
+  <head>
+    <title>File server is running</title>
+  </head>
+  <body>
+    <h1>File server is running</h1>
+
+    <p>
+      Your WebDAV file server for username {{ username }} is running. The
+      URL to enter into a WebDAV client is:
+    </p>
+
+    <pre>{{ base_url }}{{ path_prefix }}/{{ username }}</pre>
+
+    <p>
+      For instructions on how to use the file server, see
+      <a href="https://rsp.lsst.io/guides/notebooks/extfileaccess/webdav/">the
+      rsp.lsst.io documentation</a>.
+    </p>
+
+    <p>
+      If you make no requests for {{ timeout | format_timedelta }}, the
+      file server will shut down and you will need to return to
+      <a href="{{ base_url }}{{ path_prefix }}">this page</a> to start it
+      again.
+    </p>
+  </body>
 </html>
diff --git a/controller/tests/data/fileserver/output/fileserver.html b/controller/tests/data/fileserver/output/fileserver.html
@@ -1,64 +1,28 @@
 <html>
-<head>
-<title>
-User Fileserver Created
-</title>
-</head>
-</body>
-<h1>
-Your fileserver is ready.
-<h1>
-
-<h2>
-Access Token
-</h2>
-
-<p> If you do not have an access token, go to <a
-href="http://127.0.0.1:8080/auth/tokens">the Gafaelfawr tokens page</a> and press
-the "Create Token" button.  </p>
-
-<p>
-Give that token a name, such as "fileserver", the "exec:notebook" scope,
-and a reasonable expiration duration, such as 1 month.
-</p>
-
-<p>
-Press "Create".
-</p>
-
-<p>
-Your token will be displayed.  Copy this token and save it somewhere
-safe; you will never be able to view it from the tokens page again.
-</p>
-
-<h2>
-Using the Fileserver
-</h2>
-
-<p>
-To use the fileserver, you will need a WebDAV client of your choice.
-Mac and Windows have built-in WebDAV clients (this is "Connect to
-Server..." or "Map Network Drive..."), as do Gnome Nautilus and
-Konqueror for Linux.  The open-source command-line client
-<a href="https://github.com/notroj/cadaver">cadaver</a> should build on
-almost any Unix-like system and will work.
-</p>
-
-<p>
-Connect to
-<a href="http://127.0.0.1:8080/files/rachel">http://127.0.0.1:8080/files/rachel</a>
-with your WebDAV client (for Konqueror, use "webdav" or "webdavs" rather
-than "http" or "https" as the protocol).  Use the token you acquired
-earlier as the password.  You can use any string for your username
-(since the token belongs to you, it identifies you), but "rachel"
-would be both accurate and traditional.
-</p>
-
-<p>
-If you make no requests in 1h, the fileserver will shut
-down.  If that occurs, simply go back to
-<a href="http://127.0.0.1:8080/files">http://127.0.0.1:8080/files</a>
-and a new fileserver will be created for you.
-</p>
-</body>
+  <head>
+    <title>File server is running</title>
+  </head>
+  <body>
+    <h1>File server is running</h1>
+
+    <p>
+      Your WebDAV file server for username rachel is running. The
+      URL to enter into a WebDAV client is:
+    </p>
+
+    <pre>http://127.0.0.1:8080/files/rachel</pre>
+
+    <p>
+      For instructions on how to use the file server, see
+      <a href="https://rsp.lsst.io/guides/notebooks/extfileaccess/webdav/">the
+      rsp.lsst.io documentation</a>.
+    </p>
+
+    <p>
+      If you make no requests for 1 hour, the
+      file server will shut down and you will need to return to
+      <a href="http://127.0.0.1:8080/files">this page</a> to start it
+      again.
+    </p>
+  </body>
 </html>