Add VersionedDocsLink and use for evergreen links to "latest" docs pa…

…ge (#177)

This PR fixes #174 with a new `VersionedDocsLink` component that reads
the docusaurus config to determine what the latest stable version is.

It also adjusts the other dynamic link to the contribution guide to use
this. This link is changed from the latest RC versions (currently 2.20)
to the current `main` version (2.21), i.e. the absolute most up-to-date
version of the contribution guide, which seems most relevant to
contributors since they'll be starting in the `main` branch.

This has a few issues with the component due to
prettier/prettier#12209, which forces us into
a very long line on the `_index.mdx` page.

I'm unclear if a broken link will be detected or not.

src/components/VersionedDocsLink.jsx

@@ -0,0 +1,61 @@
+import Link from "@docusaurus/Link";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+
+const docsPluginPath = "./src/js/docsPluginWithTopLevel404.js";
+
+// extract the plugin configuration from docusaurus and use this to deduce the "version" references
+// for the link component
+const useVersionConfigs = () => {
+  const { siteConfig } = useDocusaurusContext();
+
+  const [_, docsPluginConfig] = siteConfig.plugins.find(
+    (pair) => pair[0] == docsPluginPath
+  );
+  if (!docsPluginConfig) {
+    throw new Error(
+      `failed to find docs plugin at ${docsPluginPath} in docusaurus.config.js; has something been renamed?`
+    );
+  }
+
+  const current = docsPluginConfig.versions.current;
+  return {
+    "current-dev": current,
+    // When running the dev server, we might be only showing the "current" docs (unless
+    // PANTSBUILD_ORG_INCLUDE_VERSIONS is set), in which lastVersion may not be set, so we just
+    // fallback to the current version to keep things working
+    "last-stable": docsPluginConfig.lastVersion
+      ? docsPluginConfig.versions[docsPluginConfig.lastVersion]
+      : current,
+  };
+};
+
+/**
+ * Link to a particular path within auto-generated docs & reference, "live" for the appropriate version.
+ *
+ * For instance, to link to /2.19/docs/introduction/welcome-to-pants
+ * for whatever the current stable version is, use:
+ *
+ *     <VersionedDocsLink version="latest-stable" unversionedPath="docs/introduction/welcome-to-pants">Welcome!</VersionedDocsLink>
+ *
+ * @param unversionedPath - the URL path without the leading /2.x/ version bit
+ * @param version - the description of the version to link to: `current-dev` (Pants' main branch), `last-stable` (most recent stable)
+ * @param linkProps - any other parameters to pass to @docusaurus/Link (including `children`)
+ */
+export default function VersionedDocsLink({
+  unversionedPath,
+  version,
+  ...linkProps
+}) {
+  const versionConfigs = useVersionConfigs();
+
+  const versionConfig = versionConfigs[version];
+  if (!versionConfig) {
+    const supported = Object.keys(versionConfigs).join(", ");
+    throw new Error(
+      `failed to find configuration for version="${version}" with unversionedPath="${unversionedPath}"; supported version values are: ${supported}`
+    );
+  }
+
+  const to = `/${versionConfig.path}/${unversionedPath}`;
+  return <Link to={to} {...linkProps} />;
+}

src/pages/_index.mdx

@@ -1,6 +1,6 @@
 import clsx from "clsx";
 import styles from "./index.module.css";
-import Link from "@docusaurus/Link";
+import VersionedDocsLink from "@site/src/components/VersionedDocsLink";
 
 export const Card = ({ children }) => {
   return (
@@ -115,8 +115,7 @@ You'll find no subsets like Starlark here. Pants empowers you with full support
 ## Pants is a multilingual multitool.
 
 Pants supports Python, Docker, Go, Java, Kotlin, Pex, Protodoc, Scala, Shell, Thrift, Protobuf,
-Docker, Helm, many linting and formatting tools, packaging, coverage, and more.
-[Learn more.](/2.19/docs/introduction/welcome-to-pants)
+Docker, Helm, many linting and formatting tools, packaging, coverage, and more. <VersionedDocsLink version="last-stable" unversionedPath="docs/introduction/welcome-to-pants"> Learn more.</VersionedDocsLink>
 
 </div>
 </div>

src/pages/community/members.mdx

@@ -1,5 +1,4 @@
-import { default as versions } from "@site/versions.json";
-import Link from "@docusaurus/Link";
+import VersionedDocsLink from "@site/src/components/VersionedDocsLink";
 
 # The Pants Community
 
@@ -25,7 +24,7 @@ Contributions come in many forms, and we appreciate all of them! Examples includ
 
 Whatever your area of expertise and your skill level, there may be valuable contributions you can make. Are you a graphic designer? A technical writer? Do you know how to make videos? There might be a cool contribution in your future.
 
-We try and make contributions easy. For example, you can suggest documentation fixes by clicking on the Suggest Edits link on any page. And you can report bugs by opening a [GitHub issue](https://github.com/pantsbuild/pants/issues). If you want to hack on the Pants codebase itself there is a <Link to={`/${versions[0]}/docs/contributions`}>helpful guide</Link>.
+We try and make contributions easy. For example, you can suggest documentation fixes by clicking on the Suggest Edits link on any page. And you can report bugs by opening a [GitHub issue](https://github.com/pantsbuild/pants/issues). If you want to hack on the Pants codebase itself there is a <VersionedDocsLink version="current-dev" unversionedPath="docs/contributions">helpful guide</VersionedDocsLink>.
 
 For some contributions, such as adding new features, the best place to get started is our [Slack workspace](/community/getting-help). You can make suggestions, solicit feedback and connect with like-minded contributors. That way we know who is working on what, and can help you avoid duplicating efforts or hitting known pitfalls.