EPMRPP-117636 || Add a version warning banner for previous documentation versions

.eslintrc

@@ -22,6 +22,7 @@
   "plugins": ["react", "prettier", "jsx-a11y", "react-hooks", "@docusaurus"],
   "rules": {
     "import/prefer-default-export": 0,
+    "react/require-default-props": 0,
     "react/no-unescaped-entities": 0,
     "import/no-unresolved": [
       0,

docusaurus.config.js

@@ -58,6 +58,10 @@ const config = {
   organizationName: 'reportportal',
   projectName: 'documentation',
 
+  customFields: {
+    productName: 'ReportPortal',
+  },
+
   i18n: {
     defaultLocale: 'en',
     locales: ['en'],

src/css/custom.css

@@ -55,6 +55,7 @@
   --ifm-dropdown-box-shadow: 0 8px 24px -4px rgba(23, 28, 41, 0.14);
   --version-selector-border-color-open: var(--ifm-color-primary);
   --navbar-button-hover-color: #fff;
+  --alert-warning-border-color: #f5a623;
 }
 
 [data-theme='light'] {
@@ -75,8 +76,11 @@
   --version-selector-border-color: var(--ifm-dropdown-border-color);
   --version-selector-divider-color: var(--ifm-dropdown-border-color);
   --version-selector-color: var(--ifm-font-color-base);
+
   --badge-secondary-bg: #eef0f4;
   --badge-secondary-color: #5F6578;
+
+  --alert-warning-background-color: #fff6e5;
 }
 
 [data-theme='dark'] {
@@ -92,9 +96,13 @@
   --version-selector-border-color: #444950;
   --version-selector-divider-color: #3a3b3d;
   --version-selector-color: #e3e3e3;
+
   --navbar-button-hover-color: var(--ifm-font-color-base);
+
   --badge-secondary-bg: #3a3b3d;
   --badge-secondary-color: #c8ccd4;
+
+  --alert-warning-background-color: #33291a;
 }
 
 button {
@@ -300,6 +308,21 @@ h1 {
   color: var(--badge-secondary-color);
 }
 
+.alert--warning {
+  --ifm-alert-background-color: var(--alert-warning-background-color);
+  --ifm-alert-border-color: var(--alert-warning-border-color);
+  --ifm-alert-foreground-color: var(--ifm-font-color-base);
+  --ifm-link-color: var(--ifm-color-primary);
+  --ifm-link-hover-color: var(--ifm-color-primary);
+  --ifm-link-decoration: none;
+
+}
+
+.alert--warning a:hover {
+  text-decoration-thickness: inherit;
+  text-decoration-color: inherit;
+}
+
 @media (min-width: 997px) {
   .version-selector-divider {
     display: inline-flex;

src/theme/DocVersionBanner/index.jsx

@@ -0,0 +1,163 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import clsx from 'clsx';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import Link from '@docusaurus/Link';
+import Translate from '@docusaurus/Translate';
+import {
+  useActivePlugin,
+  useDocVersionSuggestions,
+  useDocsPreferredVersion,
+  useDocsVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import { ThemeClassNames } from '@docusaurus/theme-common';
+
+function UnreleasedVersionLabel({ productName, versionMetadata }) {
+  return (
+    <Translate
+      id="theme.docs.versions.unreleasedVersionLabel"
+      description="The label used to tell the user that he's browsing an unreleased doc version"
+      values={{
+        productName,
+        versionLabel: <b>{versionMetadata.label}</b>,
+      }}
+    >
+      {'You are viewing unreleased {productName} documentation version {versionLabel}.'}
+    </Translate>
+  );
+}
+
+UnreleasedVersionLabel.propTypes = {
+  productName: PropTypes.string.isRequired,
+  versionMetadata: PropTypes.shape({
+    label: PropTypes.string,
+  }).isRequired,
+};
+
+function UnmaintainedVersionLabel({ productName, versionMetadata }) {
+  return (
+    <Translate
+      id="theme.docs.versions.unmaintainedVersionLabel"
+      description="The label used to tell the user that he's browsing an unmaintained doc version"
+      values={{
+        productName,
+        versionLabel: <b>{versionMetadata.label}</b>,
+      }}
+    >
+      {'You are viewing {productName} documentation version {versionLabel}.'}
+    </Translate>
+  );
+}
+
+UnmaintainedVersionLabel.propTypes = {
+  productName: PropTypes.string.isRequired,
+  versionMetadata: PropTypes.shape({
+    label: PropTypes.string,
+  }).isRequired,
+};
+
+const BannerLabelComponents = {
+  unreleased: UnreleasedVersionLabel,
+  unmaintained: UnmaintainedVersionLabel,
+};
+
+function BannerLabel({ productName, versionMetadata }) {
+  const BannerLabelComponent = BannerLabelComponents[versionMetadata.banner];
+  return <BannerLabelComponent productName={productName} versionMetadata={versionMetadata} />;
+}
+
+BannerLabel.propTypes = {
+  productName: PropTypes.string.isRequired,
+  versionMetadata: PropTypes.shape({
+    banner: PropTypes.oneOf(['unreleased', 'unmaintained']),
+    label: PropTypes.string,
+  }).isRequired,
+};
+
+function LatestVersionSuggestionLabel({ versionLabel, to, onClick }) {
+  return (
+    <Translate
+      id="theme.docs.versions.latestVersionSuggestionLabel"
+      description="The label used to tell the user to check the latest version"
+      values={{
+        versionLabel,
+        latestVersionLink: (
+          <Link to={to} onClick={onClick}>
+            <Translate
+              id="theme.docs.versions.latestVersionLinkLabel"
+              description="The label used for the latest version suggestion link label"
+            >
+              latest documentation
+            </Translate>
+          </Link>
+        ),
+      }}
+    >
+      {
+        'For the latest features and updates, please visit the {latestVersionLink} ({versionLabel}).'
+      }
+    </Translate>
+  );
+}
+
+LatestVersionSuggestionLabel.propTypes = {
+  versionLabel: PropTypes.string.isRequired,
+  to: PropTypes.string.isRequired,
+  onClick: PropTypes.func.isRequired,
+};
+
+function DocVersionBannerEnabled({ className = undefined, versionMetadata }) {
+  const {
+    siteConfig: { customFields },
+  } = useDocusaurusContext();
+  const productName = customFields?.productName ?? 'ReportPortal';
+  const { pluginId } = useActivePlugin({ failfast: true });
+  const getVersionMainDoc = (version) => version.docs.find((doc) => doc.id === version.mainDocId);
+  const { savePreferredVersionName } = useDocsPreferredVersion(pluginId);
+  const { latestDocSuggestion, latestVersionSuggestion } = useDocVersionSuggestions(pluginId);
+  // Try to link to same doc in latest version (not always possible), falling
+  // back to main doc of latest version
+  const latestVersionSuggestedDoc =
+    latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
+  return (
+    <div
+      className={clsx(
+        className,
+        ThemeClassNames.docs.docVersionBanner,
+        'alert alert--warning margin-bottom--md',
+      )}
+      role="alert"
+    >
+      <div>
+        <BannerLabel productName={productName} versionMetadata={versionMetadata} />
+      </div>
+      <div className="margin-top--md">
+        <LatestVersionSuggestionLabel
+          versionLabel={latestVersionSuggestion.label}
+          to={latestVersionSuggestedDoc.path}
+          onClick={() => savePreferredVersionName(latestVersionSuggestion.name)}
+        />
+      </div>
+    </div>
+  );
+}
+
+DocVersionBannerEnabled.propTypes = {
+  className: PropTypes.string,
+  versionMetadata: PropTypes.shape({
+    banner: PropTypes.oneOf(['unreleased', 'unmaintained']),
+    label: PropTypes.string,
+  }).isRequired,
+};
+
+export default function DocVersionBanner({ className = undefined }) {
+  const versionMetadata = useDocsVersion();
+  if (versionMetadata.banner) {
+    return <DocVersionBannerEnabled className={className} versionMetadata={versionMetadata} />;
+  }
+  return null;
+}
+
+DocVersionBanner.propTypes = {
+  className: PropTypes.string,
+};