Show per page documentation

Fixes: cockpit-project#10198
Closes: cockpit-project#13376

doc/guide/packages.xml

@@ -186,6 +186,12 @@ $ cockpit-bridge --packages
         <listitem><para>The relative path to the HTML file within the package that implements
           the menu item or tool.</para></listitem>
       </varlistentry>
+      <varlistentry>
+        <term>docs</term>
+        <listitem><para>List of documentation URLs for the given page.
+          Each item is an object containing <code>label</code> and <code>url</code>.
+        </para></listitem>
+      </varlistentry>
       <varlistentry>
         <term>keywords</term>
         <listitem><para>Keywords that describe the page and which are used for searching.

pkg/dashboard/manifest.json.in

@@ -7,6 +7,12 @@
     "dashboard": {
         "index": {
             "label": "Dashboard",
+            "docs": [
+                {
+                    "label": "Managing remote systems",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-remote-systems-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "order": 10,
             "wants": "multiple-machines",
             "icon": "fa-tachometer"

pkg/kdump/manifest.json.in

@@ -7,6 +7,12 @@
     "tools": {
         "index": {
             "label": "Kernel Dump",
+            "docs": [
+                {
+                    "label": "Configuring kdump",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/configuring-kdump-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["kdump", "crash"]

pkg/machines/manifest.json.in

@@ -9,6 +9,12 @@
         "label": "Virtual Machines",
         "path": "index.html",
         "order": 60,
+        "docs": [
+            {
+                "label": "Managing virtual machines",
+                "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/using-the-rhel-8-web-console-for-managing-vms_system-management-using-the-rhel-8-web-console"
+            }
+        ],
         "keywords": [
             {
                 "matches": ["iso", "pxe", "qcow2", "libvirt", "vm", "qemu"]

pkg/networkmanager/manifest.json.in

@@ -9,6 +9,16 @@
         "index": {
             "label": "Networking",
             "order": 40,
+            "docs": [
+                {
+                    "label": "Managing networking",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-networking-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                },
+                {
+                    "label": "Managing firewall",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/using-the-web-console-for-managing-firewall_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["network", "interface", "bridge", "vlan", "bond", "team", "port", "mac", "ipv4", "ipv6"]

pkg/packagekit/manifest.json.in

@@ -9,6 +9,12 @@
     "tools": {
         "index": {
             "label": "Software Updates",
+            "docs": [
+                {
+                    "label": "Managing software updates",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-software-updates-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["package", "packagekit", "dnf", "yum", "apt-get", "security"]

pkg/shell/base_index.js

@@ -1018,6 +1018,7 @@ function CompiledComponents() {
                     order: info.order === undefined ? 1000 : info.order,
                     icon: info.icon,
                     wants: info.wants,
+                    docs: info.docs,
                     keywords: info.keywords || [{ matches: [] }],
                     keyword: { score: -1 }
                 };

pkg/shell/index.html

@@ -42,6 +42,14 @@
               <li id="navbar-oops" hidden>
                 <a role="link" tabindex="0"><span class="oops-status" translate="yes">Ooops!</span></a>
               </li>
+              <li id="navbar-docs" class=dropdown">
+                <a role="link" tabindex="0" id="navbar-docs-dropdown" class="dropdown-toggle" data-toggle="dropdown">
+                  <span class="pficon pficon-help"></span>
+                  <span translate>Help</span>
+                </a>
+                <ul id="navbar-docs-items" class="dropdown-menu">
+                </ul>
+              </li>
               <li class="dropdown">
                 <a role="link" tabindex="0" id="navbar-dropdown" class="dropdown-toggle" data-toggle="dropdown">
                   <span class="pficon pficon-user"></span>

pkg/shell/indexes.js

@@ -287,6 +287,7 @@ function MachinesIndex(index_options, machines, loader, mdialogs) {
 
         update_navbar(machine, state, compiled);
         update_frame(machine, state, compiled);
+        update_docs(machine, state, compiled);
 
         /* Just replace the state, and URL */
         index.jump(state, true);
@@ -583,6 +584,38 @@ function MachinesIndex(index_options, machines, loader, mdialogs) {
         update_active_machine(machine ? machine.address : null);
     }
 
+    function update_docs(machine, state, compiled) {
+        const item = compiled.items[state.component];
+        const docs_items = document.getElementById("navbar-docs-items");
+        docs_items.innerHTML = "";
+
+        function create_item(name, url) {
+            const el_li = document.createElement("li");
+            const el_a = document.createElement("a");
+            const el_icon = document.createElement("i");
+            el_icon.className = "fa fa-external-link fa-xs";
+            el_a.setAttribute("translate", "yes");
+            el_a.setAttribute("href", url);
+            el_a.setAttribute("target", "blank");
+            el_a.setAttribute("rel", "noopener noreferrer");
+
+            el_a.appendChild(document.createTextNode(name));
+            el_a.appendChild(el_icon);
+
+            el_li.appendChild(el_a);
+            docs_items.appendChild(el_li);
+        }
+
+        const os_release = JSON.parse(window.localStorage['os-release'] || "{}");
+        if (os_release.DOCUMENTATION_URL)
+            create_item(cockpit.format(_("$0 documentation"), os_release.NAME), os_release.DOCUMENTATION_URL);
+
+        create_item(_("Web Console"), "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/index");
+
+        if (item && item.docs && item.docs.length > 0)
+            item.docs.forEach(e => create_item(_(e.label), e.url));
+    }
+
     function update_navbar(machine, state, compiled) {
         /* When a dashboard no machine or sidebar */
         var item = compiled.items[state.component];

pkg/shell/shell.less

@@ -299,6 +299,18 @@ html.index-page body {
     width: 100px;
 }
 
+/* navbar documentation */
+
+#navbar-docs-items a {
+    color: var(--color-link)
+}
+
+#navbar-docs .dropdown-menu a i.fa{
+    padding-left: 5px;
+    vertical-align: baseline;
+}
+
+
 /* navbar styles */
 
 .navbar-pf .navbar-toggle {
@@ -1027,4 +1039,4 @@ It is less bad than using !important, at least.
             left: 5px;
         }
     }
-}
+}

pkg/storaged/manifest.json.in

@@ -9,6 +9,16 @@
         "index": {
             "label": "Storage",
             "order": 30,
+            "docs": [
+                {
+                    "label": "Managing partitions",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-partitions-using-the-web-console_system-management-using-the-rhel-8-web-console"
+                },
+                {
+                    "label": "Managing storage devices",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-storage-devices-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["filesystem", "partition", "nfs", "raid", "volume", "disk", "vdo", "iscsi", "drive", "mount", "unmount", "udisks", "mkfs", "format", "fstab", "lvm2", "luks", "encryption", "nbde", "tang"]

pkg/systemd/manifest.json.in

@@ -10,6 +10,12 @@
         "index": {
             "label": "Overview",
             "order": 10,
+            "docs": [
+                {
+                    "label": "Configuring system settings",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/configuring-system-settings-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["time", "date", "restart", "shut", "domain", "machine", "operating system", "os", "asset tag", "ssh", "power", "version", "host"]
@@ -27,6 +33,12 @@
         "services": {
             "label": "Services",
             "order": 100,
+            "docs": [
+                {
+                    "label": "Managing services",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-services-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["service", "systemd", "target", "socket", "timer", "path", "unit", "systemctl"]
@@ -40,6 +52,12 @@
         "logs": {
             "label": "Logs",
             "order": 20,
+            "docs": [
+                {
+                    "label": "Reviewing logs",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/reviewing-logs_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["journal", "warning", "error", "debug"]

pkg/users/manifest.json.in

@@ -8,6 +8,12 @@
         "index": {
             "label": "Accounts",
             "order": 70,
+            "docs": [
+                {
+                    "label": "Managing user accounts",
+                    "url": "https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-user-accounts-in-the-web-console_system-management-using-the-rhel-8-web-console"
+                }
+            ],
             "keywords": [
                 {
                     "matches": ["user", "password", "useradd", "passwd", "username", "login", "access", "roles", "ssh", "keys"]

po/manifest2po

@@ -106,6 +106,15 @@ function process_keywords(keywords) {
     });
 }
 
+function process_docs(docs) {
+    docs.forEach(doc => {
+        push({
+            msgid: doc.label,
+            locations: [ filename ]
+        })
+    });
+}
+
 function process_menu(menu) {
     for (var m in menu) {
         if (menu[m].label) {
@@ -116,6 +125,8 @@ function process_menu(menu) {
         }
         if (menu[m].keywords)
             process_keywords(menu[m].keywords);
+        if (menu[m].docs)
+            process_docs(menu[m].docs);
     }
 }
 

src/common/cockpitsystem.c

@@ -42,6 +42,7 @@ static const gchar *os_release_fields[] = {
   "VARIANT",
   "VARIANT_ID",
   "CPE_NAME",
+  "DOCUMENTATION_URL",
   NULL
 };
 

src/ws/cockpithandlers.c

@@ -299,7 +299,7 @@ build_environment (GHashTable *os_release)
    * the corresponding information is not a leak.
    */
   static const gchar *release_fields[] = {
-    "NAME", "ID", "PRETTY_NAME", "VARIANT", "VARIANT_ID", "CPE_NAME", "ID_LIKE"
+    "NAME", "ID", "PRETTY_NAME", "VARIANT", "VARIANT_ID", "CPE_NAME", "ID_LIKE", "DOCUMENTATION_URL"
   };
 
   static const gchar *prefix = "\n    <script>\nvar environment = ";

test/verify/check-pages

@@ -24,6 +24,21 @@ from testlib import *
 
 
 class TestPages(MachineCase):
+    def checkDocs(self, items):
+        m = self.machine
+        b = self.browser
+
+        b.click("#navbar-docs > a")
+        b.wait_visible("#navbar-docs-items")
+        expected = "Web Console"
+        expected += "".join(items)
+        # DOCUMENTATION_URL is only in Fedora
+        # RHEL is tracked in rhbz#1789984
+        if "fedora" in m.image:
+            expected = "Fedora documentation" + expected
+        b.wait_collected_text("#navbar-docs-items", expected)
+        b.click("#navbar-docs > a")
+        b.wait_not_visible("#navbar-docs-items")
 
     def testBasic(self):
         m = self.machine
@@ -65,11 +80,18 @@ OnCalendar=daily
         b.enter_page("/system/services")
         b.reload()
         b.enter_page("/system/services")
-        if m.image in ["rhel-8-1-distropkg"]: # Changed in #12265
-            b.wait_text("#service-unit .panel-heading", "Test Service")
-        else:
-            b.wait_text(".service-name", "Test Service")
-
+        b.wait_text(".service-name", "Test Service")
+        if m.image not in ["rhel-8-2-distropkg"]: # Changed in #13376
+            b.switch_to_top()
+            self.checkDocs(["Managing services"])
+            b.click("#navbar-docs > a")
+            b.wait_visible('#navbar-docs-items a:contains("Managing services")[href="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/managing-services-in-the-web-console_system-management-using-the-rhel-8-web-console"]')
+            b.wait_visible('#navbar-docs-items a:contains("Web Console")[href="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_systems_using_the_rhel_8_web_console/index"]')
+            b.click("#navbar-docs > a")
+            b.wait_not_visible("#navbar-docs-items")
+            b.go("/network")
+            self.checkDocs(["Managing networking", "Managing firewall"])
+            b.go("/system/services")
 
         m.restart_cockpit()
         b.relogin("/system/services")
@@ -84,6 +106,8 @@ OnCalendar=daily
         b.enter_page("/system")
         b.wait_present("#system_information_systime_button")
         b.switch_to_top()
+        if m.image not in ["rhel-8-2-distropkg"]: # Changed in #13376
+            self.checkDocs(["Configuring system settings"])
         b.click("a[href='/system/services']")
         b.enter_page("/system/services")
         b.wait_present("ol.breadcrumb")