Improved user guide, added CI vale for docs (#2308)

* restructured user guide, minor fixes * added index file for user guide * github actions for vale * testing workflow * CI vale * changes as per vale's suggestions * set CI vale on pull request * adding homebrew script to macos infra setup file * fix CI errors * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * testing vale * vale testing complete * vale cleanup * vale test * vale test for github-pr-check * vale test for github-pr-check * vale test for github-pr-check * vale test for github-pr-check * testing vale warnings * testing vale warnings * testing vale warnings * testing vale warnings * testing vale warnings * testing vale warnings * testing vale warnings * swizzled doc cards to add icons * Align CI params to other CIs --------- Co-authored-by: Félix Malfait <felix.malfait@gmail.com>
2023-11-03 21:02:30 +05:00
parent c397619100
commit 2221c68dff
52 changed files with 219 additions and 11 deletions
--- a/docs/src/theme/DocCard/index.js
+++ b/docs/src/theme/DocCard/index.js
@ -0,0 +1,97 @@
+import React from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import {
+  findFirstCategoryLink,
+  useDocById,
+} from '@docusaurus/theme-common/internal';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import {translate} from '@docusaurus/Translate';
+import styles from './styles.module.css';
+import * as icons from "../icons"; 
+
+
+function CardContainer({href, children}) {
+  return (
+    <Link
+      href={href}
+      className={clsx('card padding--lg', styles.cardContainer)}>
+      {children}
+    </Link>
+  );
+}
+function CardLayout({href, icon, title, description}) {
+  return (
+    <CardContainer href={href}>
+      <h2 className={clsx("text--truncate", styles.cardTitle)} title={title}>
+        <span className={styles.icon}>
+          {typeof icon === "function" ? icon() : icon}
+        </span>{" "}
+        {title}
+      </h2>
+      {description && (
+        <p
+          className={clsx("text--truncate", styles.cardDescription)}
+          title={description}
+        >
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+
+function CardCategory({item}) {
+  const href = findFirstCategoryLink(item);
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+  return (
+    <CardLayout
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={
+        item.description ??
+        translate(
+          {
+            message: '{count} items',
+            id: 'theme.docs.DocCard.categoryDescription',
+            description:
+              'The default description for a category card in the generated index about how many items this category includes',
+          },
+          {count: item.items.length},
+        )
+      }
+    />
+  );
+}
+
+
+function CardLink({ item }) {
+  const customIcon = item.customProps.icon;
+  const icon = icons[customIcon] || (isInternalUrl(item.href) ? "📄️" : "🔗");
+  const doc = useDocById(item.docId ?? undefined);
+
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+
+
+export default function DocCard({item}) {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item} />;
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}
--- a/docs/src/theme/DocCard/styles.module.css
+++ b/docs/src/theme/DocCard/styles.module.css
@ -0,0 +1,33 @@
+.cardContainer {
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-700);
+  --ifm-link-hover-decoration: none;
+
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: all var(--ifm-transition-fast) ease;
+  transition-property: border, box-shadow;
+}
+
+.cardContainer:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+}
+
+.cardContainer *:last-child {
+  margin-bottom: 0;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+    display: flex
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+}
+
+.icon {
+  font-size: 1.5rem;
+  padding-right: 0.5rem;
+}