docs: minor tweaks (#4323)

This pull request includes several changes to the documentation and build process, focusing on simplifying commands, updating documentation structure, and improving code consistency. ### Build process improvements: * [`.github/workflows/ci.yml`](diffhunk://#diff-b803fcb7f17ed9235f1e5cb1fcd2f5d3b2838429d4368ae4c57ce4436577f03fL180-R181): Simplified the build steps by replacing `pnpm build` with `just build-docs` for building the website. * [`Justfile`](diffhunk://#diff-2f90408c2b0302b1cdb7f5d634114750837f940fa82d13057d9c18d0170a7e5cL239-R239): Updated `pnpm-install` command to use `pnpm-workspace.yaml` for better dependency management and added a new `build-docs` command. [[1]](diffhunk://#diff-2f90408c2b0302b1cdb7f5d634114750837f940fa82d13057d9c18d0170a7e5cL239-R239) [[2]](diffhunk://#diff-2f90408c2b0302b1cdb7f5d634114750837f940fa82d13057d9c18d0170a7e5cR318-R321) ### Documentation structure updates: * [`docs/docs/getting-started/introduction.md`](diffhunk://#diff-f849d4575ef32f8f18b0e60379feb3cc4d11b58a0b4a7a2c9b0cf1cbffb123c7L1-L9): Removed the introduction page to streamline the documentation. * [`docs/docs/getting-started/quick-start.md`](diffhunk://#diff-e867e9aaaf0dba6bd41e78aa9e911594f6b6de998395d7c98b500c158b10d547L2-R2): Promoted the Quick Start guide to the first position in the sidebar and updated installation instructions for clarity. [[1]](diffhunk://#diff-e867e9aaaf0dba6bd41e78aa9e911594f6b6de998395d7c98b500c158b10d547L2-R2) [[2]](diffhunk://#diff-e867e9aaaf0dba6bd41e78aa9e911594f6b6de998395d7c98b500c158b10d547L15-R28) [[3]](diffhunk://#diff-e867e9aaaf0dba6bd41e78aa9e911594f6b6de998395d7c98b500c158b10d547L43-R43) * [`docs/docusaurus.config.ts`](diffhunk://#diff-9dbe126a5a498e56dcf30f25d7fc163f8443517db03458905d3d33303e1cdbf9L117-R118): Updated the navigation link to point to the Quick Start guide instead of the removed introduction page. ### Code consistency improvements: * [`docs/sidebars.ts`](diffhunk://#diff-6e908f6e4016ad389cfb93ce7a47df677247c0f9d17c3589710592e8cf9527e0L1-R1): Refactored sidebar configuration to use autogenerated sections for better maintainability. [[1]](diffhunk://#diff-6e908f6e4016ad389cfb93ce7a47df677247c0f9d17c3589710592e8cf9527e0L1-R1) [[2]](diffhunk://#diff-6e908f6e4016ad389cfb93ce7a47df677247c0f9d17c3589710592e8cf9527e0L25-R28) [[3]](diffhunk://#diff-6e908f6e4016ad389cfb93ce7a47df677247c0f9d17c3589710592e8cf9527e0L37-R48) * [`docs/src/pages/index.tsx`](diffhunk://#diff-1ba1eb6028465b3f14984c99c34cb59fe12f7b2656a368200ba8bec7eb738946L1-R76): Applied consistent formatting and coding standards across the file. [[1]](diffhunk://#diff-1ba1eb6028465b3f14984c99c34cb59fe12f7b2656a368200ba8bec7eb738946L1-R76) [[2]](diffhunk://#diff-1ba1eb6028465b3f14984c99c34cb59fe12f7b2656a368200ba8bec7eb738946L83-R85)
block · Feb 6, 2025 · 0037b8b · 0037b8b
1 parent b6d05d9
commit 0037b8b
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 69 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -177,10 +177,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: cashapp/[email protected]
-      - name: Install dependencies
-        run: just pnpm-install
       - name: Build website
-        run: cd docs && pnpm build
+        run: just build-docs
   gen-lsp:
     name: Generate LSP Help
     runs-on: ubuntu-latest

diff --git a/Justfile b/Justfile
@@ -236,7 +236,7 @@ format-frontend:
 
 # Install Node dependencies using pnpm
 pnpm-install:
-  @mk node_modules/.modules.yaml : pnpm-lock.yaml -- @retry 3 pnpm install --frozen-lockfile
+  @mk $(yq '.packages[] | . + "/node_modules"' pnpm-workspace.yaml) node_modules/.modules.yaml : pnpm-lock.yaml -- @retry 3 pnpm install --frozen-lockfile
 
 # Copy plugin protos from the SQLC release
 update-sqlc-plugin-codegen-proto:
@@ -315,6 +315,10 @@ lint-scripts:
 docs: pnpm-install
   @cd docs && pnpm start
 
+# Build docs
+build-docs: pnpm-install
+  @cd docs && pnpm build
+
 # Generate LSP hover help text
 lsp-generate:
   @mk internal/lsp/hoveritems.go : internal/lsp docs/docs -- ftl-gen-lsp

diff --git a/docs/docs/getting-started/introduction.md b/docs/docs/getting-started/introduction.md
diff --git a/docs/docs/getting-started/quick-start.md b/docs/docs/getting-started/quick-start.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 title: Quick Start
 description: One page summary of how to start a new FTL project
 ---
@@ -12,20 +12,20 @@ One page summary of how to start a new FTL project.
 
 ### Install the FTL CLI
 
-Install the FTL CLI via [Homebrew](https://brew.sh/), [Hermit](https://cashapp.github.io/hermit), or manually.
+Install the FTL CLI on Mac or Linux via [Homebrew](https://brew.sh/), [Hermit](https://cashapp.github.io/hermit), or manually.
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 <Tabs groupId="package-manager">
-  <TabItem value="homebrew" label="Homebrew (Mac or Linux)" default>
+  <TabItem value="homebrew" label="Homebrew" default>
 
 ```bash
 brew tap block/ftl && brew install ftl
 ```
 
   </TabItem>
-  <TabItem value="hermit" label="Hermit (Mac or Linux)">
+  <TabItem value="hermit" label="Hermit">
 
 FTL can be installed from the main Hermit package repository by simply:
 
@@ -40,7 +40,7 @@ sources = ["https://github.com/block/hermit-ftl.git", "https://github.com/cashap
 ```
 
   </TabItem>
-  <TabItem value="manual" label="Manually (Mac or Linux)">
+  <TabItem value="manual" label="Manually">
 
 Download binaries from the [latest release page](https://github.com/block/ftl/releases/latest) and place them in your `$PATH`.
 
@@ -251,4 +251,4 @@ public class OtherVerb {
 Note that the `EchoClient` is generated by FTL and must be imported. Unfortunately at the moment JVM based languages have a bit of a chicken-and-egg problem with the generated clients. To force a dependency between the modules you need to add an import on a class that does not exist yet, and then FTL will generate the client for you. This will be fixed in the future.
 
   </TabItem>
-</Tabs> 
+</Tabs>
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -114,8 +114,8 @@ const config: Config = {
           title: 'Docs',
           items: [
             {
-              label: 'Getting Started',
-              to: '/docs/getting-started/introduction',
+              label: 'Quickstart',
+              to: '/docs/getting-started/quick-start',
             },
           ],
         },

diff --git a/docs/sidebars.ts b/docs/sidebars.ts
@@ -1,4 +1,4 @@
-import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'
 
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
@@ -22,8 +22,10 @@ const sidebars: SidebarsConfig = {
       },
       collapsed: false,
       items: [
-        'getting-started/introduction',
-        'getting-started/quick-start',
+        {
+          type: 'autogenerated',
+          dirName: 'getting-started',
+        },
       ],
     },
     {
@@ -34,21 +36,13 @@ const sidebars: SidebarsConfig = {
       },
       collapsed: false,
       items: [
-        'reference/verbs',
-        'reference/types',
-        'reference/visibility',
-        'reference/databases',
-        'reference/cron',
-        'reference/ingress',
-        'reference/secretsconfig',
-        'reference/pubsub',
-        'reference/retries',
-        'reference/externaltypes',
-        'reference/unittests',
-        'reference/matrix',
+        {
+          type: 'autogenerated',
+          dirName: 'reference',
+        },
       ],
     },
   ],
-};
+}
 
-export default sidebars;
+export default sidebars
diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx
@@ -1,77 +1,79 @@
-import type {ReactNode} from 'react';
-import clsx from 'clsx';
-import Link from '@docusaurus/Link';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import Layout from '@theme/Layout';
-import Heading from '@theme/Heading';
+import type { ReactNode } from 'react'
+import clsx from 'clsx'
+import Link from '@docusaurus/Link'
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext'
+import Layout from '@theme/Layout'
+import Heading from '@theme/Heading'
 
-import styles from './index.module.css';
+import styles from './index.module.css'
 
 const features = [
   {
     title: 'Infrastructure as code',
-    content: 'Not YAML. Declare your infrastructure in the same language you\'re writing in as type-safe values, rather than in separate configuration files disassociated from their point of use.',
+    content:
+      "Not YAML. Declare your infrastructure in the same language you're writing in as type-safe values, rather than in separate configuration files disassociated from their point of use.",
   },
   {
     title: 'Language agnostic',
-    content: 'FTL makes it possible to write backend code in your language of choice. You write normal code, and FTL extracts a service interface from your code directly, making your functions and types automatically available to all supported languages.',
+    content:
+      'FTL makes it possible to write backend code in your language of choice. You write normal code, and FTL extracts a service interface from your code directly, making your functions and types automatically available to all supported languages.',
   },
   {
     title: 'Fearless development against production',
     content: 'There is no substitute for production data. FTL plans to support forking of production infrastructure and code during development.',
   },
   {
     title: 'Fearlessly modify types',
-    content: 'Multiple versions of a single verb with different signatures can be live concurrently. See <a href="https://www.unison-lang.org/">Unison</a> for inspiration. We can statically detect changes that would violate runtime and persistent data constraints.',
+    content:
+      'Multiple versions of a single verb with different signatures can be live concurrently. See <a href="https://www.unison-lang.org/">Unison</a> for inspiration. We can statically detect changes that would violate runtime and persistent data constraints.',
   },
   {
     title: 'AI from the ground up',
-    content: 'We plan to integrate AI sensibly and deeply into the FTL platform. Automated AI-driven tuning suggestions, automated third-party API integration, and so on.',
+    content:
+      'We plan to integrate AI sensibly and deeply into the FTL platform. Automated AI-driven tuning suggestions, automated third-party API integration, and so on.',
   },
-];
+]
 
 function HomepageHeader() {
-  const {siteConfig} = useDocusaurusContext();
+  const { siteConfig } = useDocusaurusContext()
   return (
     <header className={clsx('hero hero--primary', styles.heroBanner)}>
-      <div className="container">
-        <Heading as="h1" className="hero__title">
+      <div className='container'>
+        <Heading as='h1' className='hero__title'>
           {siteConfig.title}
         </Heading>
-        <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <p className='hero__subtitle'>{siteConfig.tagline}</p>
         <div className={styles.buttons}>
-          <Link
-            className="button button--secondary button--lg"
-            to="/docs/getting-started/introduction">
+          <Link className='button button--secondary button--lg' to='/docs/getting-started/quick-start'>
             Get started
           </Link>
         </div>
         <div className={styles.version}>
-          <p><a href="https://github.com/block/ftl">Open-source Apache License</a></p>
+          <p>
+            <a href='https://github.com/block/ftl'>Open-source Apache License</a>
+          </p>
         </div>
       </div>
     </header>
-  );
+  )
 }
 
-function Feature({title, content}: {title: string; content: string}) {
+function Feature({ title, content }: { title: string; content: string }) {
   return (
     <div className={styles.feature}>
-      <Heading as="h3">{title}</Heading>
-      <p dangerouslySetInnerHTML={{__html: content}} />
+      <Heading as='h3'>{title}</Heading>
+      <p dangerouslySetInnerHTML={{ __html: content }} />
     </div>
-  );
+  )
 }
 
 export default function Home(): ReactNode {
-  const {siteConfig} = useDocusaurusContext();
+  const { siteConfig } = useDocusaurusContext()
   return (
-    <Layout
-      title={siteConfig.title}
-      description={siteConfig.tagline}>
+    <Layout title={siteConfig.title} description={siteConfig.tagline}>
       <HomepageHeader />
       <main>
-        <div className="container">
+        <div className='container'>
           <div className={styles.features}>
             {features.map((props, idx) => (
               <Feature key={idx} {...props} />
@@ -80,5 +82,5 @@ export default function Home(): ReactNode {
         </div>
       </main>
     </Layout>
-  );
+  )
 }