From f8492d4d9919f8efafddc6fdfee84fde08634b5d Mon Sep 17 00:00:00 2001 From: Luke Russell <31357343+lukegalbraithrussell@users.noreply.github.com> Date: Thu, 31 Oct 2024 13:21:54 -0700 Subject: [PATCH] Docs: salesforce compliance adjustments (#1581) --- docs/README.md | 4 +- docs/docusaurus.config.js | 246 +++++++++++--------------------------- docs/footerConfig.js | 19 +++ docs/navbarConfig.js | 88 ++++++++++++++ docs/package-lock.json | 13 +- docs/package.json | 8 +- docs/sidebars.js | 121 ++++++++----------- 7 files changed, 248 insertions(+), 251 deletions(-) create mode 100644 docs/footerConfig.js create mode 100644 docs/navbarConfig.js diff --git a/docs/README.md b/docs/README.md index 117b0348..ddfb095c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,7 +20,9 @@ docs/ │ └── oslo.svg ├── src/ │ └── theme (only contains the 404 page) -├── docusaurus.config.js (main config file. also where to set navbar/footer) +├── docusaurus.config.js (main config file) +├── footerConfig.js (footer. go to main repo to change) +├── navbarConfig.js (navbar. go to main repo to change) └── sidebar.js (manually set where the content docs are in the sidebar.) ``` diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 5f7ab587..3664238b 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -1,186 +1,84 @@ -// @ts-check -// `@type` JSDoc annotations allow editor autocompletion and type checking -// (when paired with `@ts-check`). -// There are various equivalent ways to declare your Docusaurus config. -// See: https://docusaurus.io/docs/api/docusaurus-config - import { themes as prismThemes } from "prism-react-renderer"; +const footer = require("./footerConfig"); +const navbar = require("./navbarConfig"); /** @type {import('@docusaurus/types').Config} */ const config = { - title: "Python Slack SDK", - tagline: "Official frameworks, libraries, and SDKs for Slack developers", - favicon: "img/favicon.ico", - - url: "https://tools.slack.dev", - baseUrl: "/python-slack-sdk/", - organizationName: "slackapi", - projectName: "python-slack-sdk", + title: "Python Slack SDK", + tagline: "Official frameworks, libraries, and SDKs for Slack developers", + favicon: "img/favicon.ico", + url: "https://tools.slack.dev", + baseUrl: "/python-slack-sdk/", + organizationName: "slackapi", + projectName: "python-slack-sdk", - onBrokenLinks: "warn", - onBrokenAnchors: "warn", - onBrokenMarkdownLinks: "warn", + onBrokenLinks: "warn", + onBrokenAnchors: "warn", + onBrokenMarkdownLinks: "warn", - i18n: { - defaultLocale: "en", - locales: ["en"], - }, + i18n: { + defaultLocale: "en", + locales: ["en"], + }, - presets: [ - [ - "classic", - /** @type {import('@docusaurus/preset-classic').Options} */ - ({ - docs: { - path: "content", - breadcrumbs: false, - routeBasePath: "/", // Serve the docs at the site's root - sidebarPath: "./sidebars.js", - editUrl: - "https://github.com/slackapi/python-slack-sdk/tree/main/docs", - }, - blog: false, - theme: { - customCss: "./src/css/custom.css", - }, - gtag: { - trackingID: "G-9H1YZW28BG", - }, - }), - ], - ], + presets: [ + [ + "classic", + /** @type {import('@docusaurus/preset-classic').Options} */ + ({ + docs: { + path: "content", + breadcrumbs: false, + routeBasePath: "/", // Serve the docs at the site's root + sidebarPath: "./sidebars.js", + editUrl: + "https://github.com/slackapi/python-slack-sdk/tree/main/docs", + }, + blog: false, + theme: { + customCss: "./src/css/custom.css", + }, + }), + ], + ], - plugins: [ - "docusaurus-theme-github-codeblock", - [ - "@docusaurus/plugin-client-redirects", - { - redirects: [], - }, - ], - ], + plugins: [ + "docusaurus-theme-github-codeblock", + [ + "@docusaurus/plugin-client-redirects", + { + redirects: [], + }, + ], + ], - themeConfig: - /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ - ({ - colorMode: { - respectPrefersColorScheme: true, - }, - docs: { - sidebar: { - autoCollapseCategories: true, - }, - }, - navbar: { - title: "Slack Developer Tools", - logo: { - alt: "Slack logo", - src: "img/slack-logo.svg", - href: "https://tools.slack.dev", - target: "_self", - }, - items: [ - { - type: "dropdown", - label: "Bolt", - position: "left", - items: [ - { - label: "Java", - to: "https://tools.slack.dev/java-slack-sdk/guides/bolt-basics", - target: "_self", - }, - { - label: "JavaScript", - to: "https://tools.slack.dev/bolt-js", - target: "_self", - }, - { - label: "Python", - to: "https://tools.slack.dev/bolt-python", - target: "_self", - }, - ], - }, - { - type: "dropdown", - label: "SDKs", - position: "left", - items: [ - { - label: "Java Slack SDK", - to: "https://tools.slack.dev/java-slack-sdk/", - target: "_self", - }, - { - label: "Node Slack SDK", - to: "https://tools.slack.dev/node-slack-sdk/", - target: "_self", - }, - { - label: "Python Slack SDK", - to: "https://tools.slack.dev/python-slack-sdk/", - target: "_self", - }, - { - label: "Deno Slack SDK", - to: "https://api.slack.com/automation/quickstart", - target: "_self", - }, - ], - }, - { - type: "dropdown", - label: "Community", - position: "left", - items: [ - { - label: "Community tools", - to: "https://tools.slack.dev/community-tools", - target: "_self", - }, - { - label: "Slack Community", - to: "https://slackcommunity.com/", - target: "_self", - }, - ], - }, - { - to: "https://api.slack.com/docs", - label: "API Docs", - target: "_self", - }, - { - type: "localeDropdown", - position: "right", - }, - { - "aria-label": "GitHub Repository", - className: "navbar-github-link", - href: "https://github.com/slackapi/python-slack-sdk", - position: "right", - target: "_self", - }, - ], - }, - footer: { - copyright: `

Made with ♡ by Slack and pals like you

`, - }, - prism: { - // switch to alucard when available in prism? - theme: prismThemes.github, - darkTheme: prismThemes.dracula, - }, - codeblock: { - showGithubLink: true, - githubLinkLabel: "View on GitHub", - }, - // announcementBar: { - // id: `announcementBar`, - // content: `🎉️ Version 2.26.0 of the developer tools for the Slack automations platform is here! 🎉️ `, - // }, - }), + themeConfig: + /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ + ({ + colorMode: { + respectPrefersColorScheme: true, + }, + docs: { + sidebar: { + autoCollapseCategories: true, + }, + }, + navbar, + footer, + prism: { + // switch to alucard when available in prism? + theme: prismThemes.github, + darkTheme: prismThemes.dracula, + }, + codeblock: { + showGithubLink: true, + githubLinkLabel: "View on GitHub", + }, + // announcementBar: { + // id: `announcementBar`, + // content: `🎉️ Version 2.26.0 of developer tools for the Slack automations platform is here! 🎉️ `, + // }, + }), }; export default config; diff --git a/docs/footerConfig.js b/docs/footerConfig.js new file mode 100644 index 00000000..9f8af804 --- /dev/null +++ b/docs/footerConfig.js @@ -0,0 +1,19 @@ +const footer = { + links: [ + { + items: [ + { + html: ` +

+ Terms of Service + Privacy Information +
+ ©2024 Slack Technologies, LLC, a Salesforce company. All rights reserved. Various trademarks held by their respective owners. + `, + }, + ], + }, + ], +}; + +module.exports = footer; diff --git a/docs/navbarConfig.js b/docs/navbarConfig.js new file mode 100644 index 00000000..c41016e3 --- /dev/null +++ b/docs/navbarConfig.js @@ -0,0 +1,88 @@ +const navbar = { + title: "Slack Developer Tools", + logo: { + src: "img/slack-logo.svg", + }, + items: [ + { + type: "dropdown", + label: "Bolt", + position: "left", + items: [ + { + label: "Java", + to: "https://tools.slack.dev/java-slack-sdk/guides/bolt-basics", + target: "_self", + }, + { + label: "JavaScript", + to: "https://tools.slack.dev/bolt-js", + target: "_self", + }, + { + label: "Python", + to: "https://tools.slack.dev/bolt-python", + target: "_self", + }, + ], + }, + { + type: "dropdown", + label: "SDKs", + position: "left", + items: [ + { + label: "Java Slack SDK", + to: "https://tools.slack.dev/java-slack-sdk/", + target: "_self", + }, + { + label: "Node Slack SDK", + to: "https://tools.slack.dev/node-slack-sdk/", + target: "_self", + }, + { + label: "Python Slack SDK", + to: "https://tools.slack.dev/python-slack-sdk/", + target: "_self", + }, + { + label: "Deno Slack SDK", + to: "https://api.slack.com/automation/quickstart", + target: "_self", + }, + ], + }, + { + type: "dropdown", + label: "Community", + position: "left", + items: [ + { + label: "Community tools", + to: "https://tools.slack.dev/community-tools", + target: "_self", + }, + { + label: "Slack Community", + to: "https://slackcommunity.com/", + target: "_self", + }, + ], + }, + { + to: "https://api.slack.com/docs", + label: "API Docs", + target: "_self", + }, + { + "aria-label": "GitHub Repository", + className: "navbar-github-link", + href: "https://github.com/slackapi", + position: "right", + target: "_self", + }, + ], +}; + +module.exports = navbar; diff --git a/docs/package-lock.json b/docs/package-lock.json index 62097d53..09610a69 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -8,9 +8,9 @@ "name": "website", "version": "2024.08.01", "dependencies": { - "@docusaurus/core": "3.5.2", + "@docusaurus/core": "^3.5.2", "@docusaurus/plugin-client-redirects": "^3.5.2", - "@docusaurus/preset-classic": "3.5.2", + "@docusaurus/preset-classic": "^3.5.2", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "docusaurus-theme-github-codeblock": "^2.0.2", @@ -19,8 +19,8 @@ "react-dom": "^18.0.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "3.5.2", - "@docusaurus/types": "3.5.2" + "@docusaurus/module-type-aliases": "^3.5.2", + "@docusaurus/types": "^3.5.2" }, "engines": { "node": ">=20.0" @@ -2239,6 +2239,7 @@ "version": "3.5.2", "resolved": "https://registry.npmjs.org/@docusaurus/core/-/core-3.5.2.tgz", "integrity": "sha512-4Z1WkhCSkX4KO0Fw5m/Vuc7Q3NxBG53NE5u59Rs96fWkMPZVSrzEPP16/Nk6cWb/shK7xXPndTmalJtw7twL/w==", + "license": "MIT", "dependencies": { "@babel/core": "^7.23.3", "@babel/generator": "^7.23.3", @@ -2389,6 +2390,7 @@ "version": "3.5.2", "resolved": "https://registry.npmjs.org/@docusaurus/module-type-aliases/-/module-type-aliases-3.5.2.tgz", "integrity": "sha512-Z+Xu3+2rvKef/YKTMxZHsEXp1y92ac0ngjDiExRdqGTmEKtCUpkbNYH8v5eXo5Ls+dnW88n6WTa+Q54kLOkwPg==", + "license": "MIT", "dependencies": { "@docusaurus/types": "3.5.2", "@types/history": "^4.7.11", @@ -2407,6 +2409,7 @@ "version": "3.5.2", "resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-3.5.2.tgz", "integrity": "sha512-GMU0ZNoVG1DEsZlBbwLPdh0iwibrVZiRfmdppvX17SnByCVP74mb/Nne7Ss7ALgxQLtM4IHbXi8ij90VVjAJ+Q==", + "license": "MIT", "dependencies": { "@docusaurus/core": "3.5.2", "@docusaurus/logger": "3.5.2", @@ -2614,6 +2617,7 @@ "version": "3.5.2", "resolved": "https://registry.npmjs.org/@docusaurus/preset-classic/-/preset-classic-3.5.2.tgz", "integrity": "sha512-3ihfXQ95aOHiLB5uCu+9PRy2gZCeSZoDcqpnDvf3B+sTrMvMTr8qRUzBvWkoIqc82yG5prCboRjk1SVILKx6sg==", + "license": "MIT", "dependencies": { "@docusaurus/core": "3.5.2", "@docusaurus/plugin-content-blog": "3.5.2", @@ -2749,6 +2753,7 @@ "version": "3.5.2", "resolved": "https://registry.npmjs.org/@docusaurus/types/-/types-3.5.2.tgz", "integrity": "sha512-N6GntLXoLVUwkZw7zCxwy9QiuEXIcTVzA9AkmNw16oc0AP3SXLrMmDMMBIfgqwuKWa6Ox6epHol9kMtJqekACw==", + "license": "MIT", "dependencies": { "@mdx-js/mdx": "^3.0.0", "@types/history": "^4.7.11", diff --git a/docs/package.json b/docs/package.json index c295a8ab..c905ae77 100644 --- a/docs/package.json +++ b/docs/package.json @@ -14,9 +14,9 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "3.5.2", + "@docusaurus/core": "^3.5.2", "@docusaurus/plugin-client-redirects": "^3.5.2", - "@docusaurus/preset-classic": "3.5.2", + "@docusaurus/preset-classic": "^3.5.2", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", "docusaurus-theme-github-codeblock": "^2.0.2", @@ -25,8 +25,8 @@ "react-dom": "^18.0.0" }, "devDependencies": { - "@docusaurus/module-type-aliases": "3.5.2", - "@docusaurus/types": "3.5.2" + "@docusaurus/module-type-aliases": "^3.5.2", + "@docusaurus/types": "^3.5.2" }, "browserslist": { "production": [ diff --git a/docs/sidebars.js b/docs/sidebars.js index aa93f12c..9fedee7c 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,75 +1,60 @@ -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ - // @ts-check /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars = { - // By default, Docusaurus generates a sidebar from the docs folder structure - // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], - - // But you can create a sidebar manually - sidebarPythonSDK: [ - { - type: "doc", - id: "index", - label: "Python Slack SDK", - className: "sidebar-title", - }, - "installation", - "web", - "webhook", - "socket-mode", - "oauth", - "audit-logs", - "rtm", - "scim", - { type: "html", value: "
" }, - { - type: "category", - label: "Legacy slackclient v2", - items: [ - "legacy/index", - "legacy/auth", - "legacy/basic_usage", - "legacy/conversations", - "legacy/real_time_messaging", - "legacy/faq", - "legacy/changelog", - ], - }, - "v3-migration", - { type: "html", value: "
" }, - { - type: "link", - label: "Reference", - href: "https://tools.slack.dev/python-slack-sdk/api-docs/slack_sdk/", - }, - { type: "html", value: "
" }, - { - type: "link", - label: "Release notes", - href: "https://github.com/slackapi/python-slack-sdk/releases", - }, - { - type: "link", - label: "Code on GitHub", - href: "https://github.com/SlackAPI/python-slack-sdk", - }, - { - type: "link", - label: "Contributors Guide", - href: "https://github.com/SlackAPI/python-slack-sdk/blob/main/.github/contributing.md", - }, - ], + sidebarPythonSDK: [ + { + type: "doc", + id: "index", + label: "Python Slack SDK", + className: "sidebar-title", + }, + "installation", + "web", + "webhook", + "socket-mode", + "oauth", + "audit-logs", + "rtm", + "scim", + { type: "html", value: "
" }, + { + type: "category", + label: "Legacy slackclient v2", + items: [ + "legacy/index", + "legacy/auth", + "legacy/basic_usage", + "legacy/conversations", + "legacy/real_time_messaging", + "legacy/faq", + "legacy/changelog", + ], + }, + "v3-migration", + { type: "html", value: "
" }, + { + type: "link", + label: "Reference", + href: "https://tools.slack.dev/python-slack-sdk/api-docs/slack_sdk/", + }, + { type: "html", value: "
" }, + { + type: "link", + label: "Release notes", + href: "https://github.com/slackapi/python-slack-sdk/releases", + }, + { + type: "link", + label: "Code on GitHub", + href: "https://github.com/SlackAPI/python-slack-sdk", + }, + { + type: "link", + label: "Contributors Guide", + href: "https://github.com/SlackAPI/python-slack-sdk/blob/main/.github/contributing.md", + }, + ], }; export default sidebars;