Merge pull request #11485 from supabase/feat/how-docs-work-doc

Feat/how docs work doc

apps/docs/DEVELOPERS.md

@@ -0,0 +1,98 @@
+# Developing Supabase Docs
+
+## Getting started
+
+Thanks for your interest in [Supabase docs](https://supabase.com/docs) and for wanting to contribute! Before you begin, read the
+[code of conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md) and check out the
+[existing issues](https://github.com/supabase/supabase/issues).
+This document describes how to set up your development environment to contribute to [Supabase docs](https://supabase.com/docs).
+
+For a complete run-down on how all of our tools work together, see the main DEVELOPERS.md. That readme describes how to get set up locally in lots of detail, including minimum requirements, our Turborepo setup, installing packages, sharing components across projects, and more. This readme deals specifically with the docs site.
+
+## Local setup
+
+[supabase.com/docs](https://supabase.com/docs) is a Next.JS site. You can get setup by following the same steps for all of our other Next.JS projects:
+
+1. Follow the steps outlined in the Local Development section of the main [DEVELOPERS.md](https://github.com/supabase/supabase/blob/master/DEVELOPERS.md)
+2. Start the local docs site by navigating to `/apps/docs` and running `npm run dev`
+3. Visit http://localhost:3001/docs in your browser - don't forget to append the `/docs` to the end
+4. Your local site should look exactly like [https://supabase.com/docs](https://supabase.com/docs)
+
+## Types of documentation
+
+[https://supabase.com/docs](https://supabase.com/docs) has several different kinds of documentation, all coming from different sources.
+
+### Guides
+
+The primary, instructional type of content. Basically anything that lives on the `https://supabase.com/docs/guides` route. This includes Guides for Auth, Database, Storage, Realtime, Edge Functions, as well as general resources, self-hosting instructions, and integrations. These are all [`.mdx`](https://mdxjs.com/) files — a combination of Markdown and Javascript.
+
+#### Things to know
+
+Here's a simple [example](https://supabase.com/docs/guides/functions) `.mdx` Guide, and here is [the source on Github](https://raw.githubusercontent.com/supabase/supabase/master/apps/docs/pages/guides/functions.mdx).
+
+Some things to note:
+
+1. The files need to import a Layout at the top
+2. The files need to export a `Page` at the bottom with the `<Layout>` component
+3. The files frontmatter is stored in `const meta = {}`. You should always include `title` and `description`.
+4. You can write Markdown as you normally would, but you can also write regular Javascript and JSX. Note the `examples` array that we iterate over.
+5. Any Javascript variables you use in these files need to be exported in order to be used (i.e., `export const examples = []`).
+
+##### Using components
+
+You can use any standard React components in these `.mdx` files without having to explicitly import them in each file. All components get imported in a [common components](https://github.com/supabase/supabase/blob/master/apps/docs/components/index.tsx) file and can be used in any `.mdx` file. Components can also be "intercepted" and modified via this file. Note how we're intercepting the `h2`, `h3` and `code` tags and modifying them before converting the `mdx` to `html`.
+
+### Reference docs for client libraries
+
+We maintain client libraries for [Javascript](https://supabase.com/docs/reference/javascript) and [Flutter/Dart](https://supabase.com/docs/reference/dart) (with more to come). These reference docs document every object and method available for developers to use. The are assembled from different sources and work much differently than the `.mdx` Guides we just looked at.
+
+The client libraries are essentially wrappers around the clients for the various tools we use — GoTrue, PostgREST, Storage, Functions, and Realtime. The easiest way to describe how the things fit together is to look at an example and trace where the various pieces of information are coming from.
+
+#### Example
+
+Let's look at the `updateUser()` function in the `supabase-js` library.
+
+#### Common file
+
+Several pieces of information for this function come from a [common file](https://github.com/supabase/supabase/blob/3d774b3b7bcdcb410e25726d832467584ebea686/spec/common-client-libs-sections.json#L548) where we store information shared by all libraries.
+
+1. id — used to identify this function
+2. title - the human-readable title
+3. slug — the url slug
+4. product - the Supabase tool or product that "owns" this function. Since `updateUser()` is an auth function, its product is `auth`
+5. type — `updateUser()` is a function and marked as such, but we can also have sections of markdown interspersed with these function definitions.
+
+When a new function is added, this info would need to be manually added to the common file.
+
+#### Function Parameters
+
+The `updateUser()` function takes one parameter: `attributes`. The details for this parameter live in the GoTrue client library, referenced via a `$ref` property in the `supabase-js` [spec file](https://github.com/supabase/supabase/blob/cb04d85262db6a371539dda7df9b00ba5a901e87/spec/supabase_js_v2.yml#L357). Here, the `$ref` property is pointing to the [actual function definition](https://github.com/supabase/gotrue-js/blob/2d60e79073b96ae8c97a6ce18e2601ed1e2a2712/src/GoTrueClient.ts#L590) in the `gotrue-js` library. The accepted values for the `attributes` parameter come from the [type definition](https://github.com/supabase/gotrue-js/blob/16d3deb822097e8640a3a15b94a5690b3beaf11b/src/lib/types.ts#L233).
+
+These individual library spec files are fetched via this [Makefile](https://github.com/supabase/supabase/blob/master/spec/Makefile), and get [transformed](https://github.com/supabase/supabase/blob/master/spec/enrichments/tsdoc_v2/supabase_dereferenced.json) to combine the information we need (params, types, etc). Unless you're a library maintainer, you shouldn't need to worry about this part of the process.
+
+If you are a library maintainer, the last important note about these library files is that the [Makefile](https://github.com/supabase/supabase/blob/master/spec/Makefile) pulls from the `gh-pages` branch of the client library repo. Here's an example of the [`realtime-js` spec file](https://github.com/supabase/realtime-js/blob/gh-pages/v2/spec.json). Updating something like function params or returns, the process is:
+
+1. Get your changes merged to `master` in your library
+2. This will kick off an action that automatically updates the spec file in the library's `gh-pages` branch
+3. Run `make` in `/spec` of the `supabase/supabase` repo. This will regenerate all of the `tsdoc` files that the docs site uses
+4. You should now see the changes you've made in the docs site locally
+
+#### Function Examples
+
+The `updateUser()` function has three examples listed with it. The examples are stored along with the `$ref` property in the [supabase_js_v2 spec file](https://github.com/supabase/supabase/blob/master/spec/supabase_js_v2.yml).
+
+#### Rendering in Next.JS
+
+These reference docs are rendered by Next.JS via a dynamic route using a [`[...slug.tsx]`](https://github.com/supabase/supabase/blob/master/apps/docs/pages/reference/javascript/%5B...slug%5D.tsx). Here, we use the library [spec file](https://github.com/supabase/supabase/blob/bd0514553c627db8f1e8d0b3ae440ccb6759d228/apps/docs/pages/reference/javascript/%5B...slug%5D.tsx#L4) and the [common file](https://github.com/supabase/supabase/blob/bd0514553c627db8f1e8d0b3ae440ccb6759d228/apps/docs/pages/reference/javascript/%5B...slug%5D.tsx#L1) to output the info you see on the page.
+
+### Other reference docs
+
+The reference docs for the [Supabase Management API](https://supabase.com/docs/reference/api) and the [Supabase CLI](https://supabase.com/docs/reference/cli) are a little more straightforward than the client libraries. Both files also have a [common file](https://github.com/supabase/supabase/blob/master/spec/common-cli-sections.json) which handles things like `title`, `id` and `slug`. Both also have a spec file detailing things like parameters, descriptions, and responses ([Management API](https://github.com/supabase/supabase/blob/master/spec/api_v0_openapi.json) / [CLI](https://github.com/supabase/supabase/blob/master/spec/cli_v1_commands.yaml))
+
+On the Next.JS side of things, these work almost exactly the same as the client libaries with a dynamic [`[...slug.tsx]`](https://github.com/supabase/supabase/blob/master/apps/docs/pages/reference/cli/%5B...slug%5D.tsx).
+
+### Misc
+
+#### Search
+
+Search is handled through Algolia. When the site is built, a [search script](https://github.com/supabase/supabase/blob/master/apps/docs/scripts/build-search.ts) runs through all of the types of content, generating search objects that are sent to Algolia to index.

apps/docs/components/Navigation/NavigationMenu/NavigationMenuRefListItems.tsx

@@ -257,20 +257,18 @@ const Content: React.FC<INavigationMenuRefList> = ({ id, lib, commonSections, sp
             <Fragment key={fn.id}>
               <RenderLink {...fn} lib={lib} />
               {fn.items &&
-                fn.items
-                  //.filter((item) => item.libs.includes(lib))
-                  .map((item) => (
-                    <RenderLink
-                      {...item}
-                      library={menu.title}
-                      index={fnIndex}
-                      modifierIds={modifierIds}
-                      filterIds={filterIds}
-                      authServerIds={authServerIds}
-                      lib={lib}
-                      allowedKeys={allowedKeys}
-                    />
-                  ))}
+                fn.items.map((item) => (
+                  <RenderLink
+                    {...item}
+                    library={menu.title}
+                    index={fnIndex}
+                    modifierIds={modifierIds}
+                    filterIds={filterIds}
+                    authServerIds={authServerIds}
+                    lib={lib}
+                    allowedKeys={allowedKeys}
+                  />
+                ))}
             </Fragment>
           ) : (
             <Fragment key={fn.title}>

apps/docs/components/Options.tsx

@@ -70,7 +70,9 @@ const Option: FC<IOption> = (props) => {
         </span>
         <span className="text-scale-900 text-xs">{props.type ?? 'no type'}</span>
       </div>
-      <p className="text-sm text-scale-1000 m-0">{props.description ?? 'nodescription'}</p>
+
+      {props.description && <p className="text-sm text-scale-1000 m-0">{props.description}</p>}
+
       {props.children}
     </div>
   )

apps/docs/components/Params.tsx

@@ -20,7 +20,9 @@ const Param: FC<IParamProps> = (paramItem) => {
         </span>
         <span className="text-scale-900 text-xs">{paramItem.type ?? 'no type'}</span>
       </div>
-      <p className="text-sm text-scale-1000 m-0">{paramItem.description ?? 'nodescription'}</p>
+      {paramItem.description && (
+        <p className="text-sm text-scale-1000 m-0">{paramItem.description} </p>
+      )}
       {paramItem.children}
     </li>
   )

apps/docs/components/index.tsx

@@ -1,4 +1,5 @@
-import { Button, Tabs, Alert } from 'ui'
+import { Button, Tabs, Alert, GlassPanel } from 'ui'
+import Link from 'next/link'
 
 // Common components
 import Admonition from './Admonition'
@@ -38,6 +39,8 @@ const components = {
   Button,
   ButtonCard,
   CodeBlock,
+  GlassPanel,
+  Link,
   Frameworks,
   AuthProviders,
   FunctionsExamples,

apps/docs/pages/guides/functions.mdx

@@ -1,6 +1,4 @@
 import Layout from '~/layouts/DefaultGuideLayout'
-import { Button, GlassPanel } from 'ui'
-import Link from 'next/link'
 
 export const meta = {
   id: 'functions',

spec/common-client-libs.yml

@@ -1,485 +0,0 @@
-openref: 0.1
-
-info:
-  id: reference/common-library-file
-  title: Supabase Client libs common
-  description: |
-
-    This file shares info common between the JS and Dart libraries.
-
-functions:
-  - id: initializing
-    title: initializing
-    slug: initializing
-
-  - id: select
-    title: 'Fetching data'
-    slug: select
-    product: database
-
-  - id: insert
-    title: 'Insert data'
-    slug: insert
-    product: 'database'
-
-  - id: update
-    title: 'Update data'
-    slug: update
-    product: 'database'
-
-  - id: upsert
-    title: 'Upsert data'
-    slug: upsert
-    product: 'database'
-
-  - id: delete
-    title: 'Delete data'
-    slug: delete
-    product: 'database'
-
-  - id: rpc
-    title: 'Postgres functions'
-    slug: rpc
-    product: 'database'
-
-  - id: using-filters
-    title: 'Using filters'
-    slug: using-filters
-    product: 'database'
-
-  - id: eq
-    title: eq()
-    slug: eq
-    product: 'database'
-    parent: 'Filters'
-
-  - id: neq
-    title: neq()
-    slug: neq
-    product: 'database'
-    parent: 'Filters'
-
-  - id: gt
-    title: gt()
-    slug: gt
-    product: 'database'
-    parent: 'Filters'
-
-  - id: gte
-    title: gte()
-    slug: gte
-    product: 'database'
-    parent: 'Filters'
-
-  - id: lt
-    title: lt()
-    slug: lt
-    product: 'database'
-    parent: 'Filters'
-
-  - id: lte
-    title: lte()
-    slug: lte
-    product: 'database'
-    parent: 'Filters'
-
-  - id: like
-    title: like()
-    slug: like
-    product: 'database'
-    parent: 'Filters'
-
-  - id: ilike
-    title: ilike()
-    slug: ilike
-    product: 'database'
-    parent: 'Filters'
-
-  - id: is
-    title: is()
-    slug: is
-    product: 'database'
-    parent: 'Filters'
-
-  - id: in
-    title: in()
-    slug: in
-    product: 'database'
-    parent: 'Filters'
-
-  - id: contains
-    title: contains()
-    slug: contains
-    product: 'database'
-    parent: 'Filters'
-
-  - id: contained-by
-    title: containedBy()
-    slug: containedby
-    product: 'database'
-    parent: 'Filters'
-
-  - id: range-gt
-    title: rangeGt()
-    slug: rangegt
-    product: 'database'
-    parent: 'Filters'
-
-  - id: range-gte
-    title: rangeGte()
-    slug: rangegte
-    product: 'database'
-    parent: 'Filters'
-
-  - id: range-lt
-    title: rangeLt()
-    slug: rangelt
-    product: 'database'
-    parent: 'Filters'
-
-  - id: range-lte
-    title: rangeLte()
-    slug: rangelte
-    product: 'database'
-    parent: 'Filters'
-
-  - id: range-adjacent
-    title: rangeAdjacent()
-    slug: rangeadjacent
-    product: 'database'
-    parent: 'Filters'
-
-  - id: overlaps
-    title: overlaps()
-    slug: overlaps
-    product: 'database'
-    parent: 'Filters'
-
-  - id: text-search
-    title: textSearch()
-    slug: textsearch
-    product: 'database'
-    parent: 'Filters'
-
-  - id: match
-    title: match()
-    slug: match
-    product: 'database'
-    parent: 'Filters'
-
-  - id: not
-    title: not()
-    slug: not
-    product: 'database'
-    parent: 'Filters'
-
-  - id: or
-    title: or()
-    slug: or
-    product: 'database'
-    parent: 'Filters'
-
-  - id: filter
-    title: filter()
-    slug: filter
-    product: 'database'
-    parent: 'Filters'
-
-  - id: using-modifiers
-    title: Using Modifiers
-    slug: using-modifiers
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: db-modifiers-select
-    title: select()
-    slug: db-modifiers-select
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: order
-    title: order()
-    slug: order
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: limit
-    title: limit()
-    slug: limit
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: range
-    title: range()
-    slug: range
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: abort-signal
-    title: abortSignal()
-    slug: db-abortsignal
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: single
-    title: single()
-    slug: single
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: maybe-single
-    title: maybeSingle()
-    slug: maybesingle
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: csv
-    title: csv()
-    slug: db-csv
-    product: 'database'
-    parent: 'Modifiers'
-
-  - id: sign-up
-    title: Sign up
-    slug: auth-signup
-    product: 'auth'
-
-  - id: sign-in
-    title: Sign in
-    slug: auth-signin
-    product: 'auth'
-
-  - id: set-auth
-    title: setAuth()
-    slug: auth-setauth
-    product: 'auth'
-
-  - id: send-mobile-otp
-    title: sendMobileOTP()
-    slug: auth-api-sendmobileotp
-    product: 'auth'
-
-  - id: sign-in-with-password
-    title: Sign in with password
-    slug: auth-signinwithpassword
-    product: 'auth'
-
-  - id: sign-in-with-otp
-    title: Sign in with OTP
-    slug: auth-signinwithotp
-    product: 'auth'
-
-  - id: sign-in-with-oauth
-    title: Sign in with 0auth
-    slug: auth-signinwithoauth
-    product: 'auth'
-
-  - id: sign-out
-    title: signOut()
-    slug: auth-signout
-    product: 'auth'
-
-  - id: verify-otp
-    title: verifyOtp()
-    slug: auth-verifyotp
-    product: 'auth'
-
-  - id: get-session
-    title: getSession()
-    slug: auth-getsession
-    product: 'auth'
-
-  - id: get-user
-    title: getUser()
-    slug: auth-getuser
-    product: 'auth'
-
-  - id: update-user
-    title: updateUser()
-    slug: auth-updateuser
-    product: 'auth'
-
-  - id: set-session
-    title: setSession()
-    slug: auth-setsession
-    product: 'auth'
-
-  - id: refresh-session
-    title: refreshSession()
-    slug: auth-refreshsession
-    product: 'auth'
-
-  - id: on-auth-state-change
-    title: onAuthStateChange()
-    slug: auth-onauthstatechange
-    product: 'auth'
-
-  - id: admin-api
-    title: Overview
-    slug: supabase-auth-admin-api
-    product: 'auth-admin'
-
-  - id: get-user-by-id
-    title: getUserById()
-    slug: auth-admin-getuserbyid
-    product: 'auth-admin'
-
-  - id: list-users
-    title: listUsers()
-    slug: auth-admin-listusers
-    product: 'auth-admin'
-
-  - id: create-user
-    title: createUser()
-    slug: auth-admin-createuser
-    product: 'auth-admin'
-
-  - id: delete-user
-    title: deleteUser()
-    slug: auth-admin-deleteuser
-    product: 'auth-admin'
-
-  - id: invite-user-by-email
-    title: inviteUserByEmail()
-    slug: auth-admin-inviteuserbyemail
-    product: 'auth-admin'
-
-  - id: reset-password-for-email
-    title: resetPasswordForEmail()
-    slug: auth-admin-resetpasswordforemail
-    product: 'auth-admin'
-
-  - id: generate-link
-    title: generateLink()
-    slug: auth-admin-generatelink
-    product: 'auth-admin'
-
-  - id: update-user-by-id
-    title: updateUserById()
-    slug: auth-admin-updateuserbyid
-    product: 'auth-admin'
-
-  - id: invoke
-    title: invoke()
-    slug: auth-admin-invoke
-    product: 'functions'
-
-  - id: stream
-    title: stream()
-    slug: stream
-    product: 'realtime'
-
-  - id: subscribe
-    title: on().subscribe()
-    slug: subscribe
-    product: 'realtime'
-
-  - id: remove-subscription
-    title: removeSubscription()
-    slug: removesubscription
-    product: 'realtime'
-
-  - id: remove-all-subscriptions
-    title: removeallsubscriptions()
-    slug: removeallsubscriptions
-    product: 'realtime'
-
-  - id: get-subscriptions
-    title: getSubscriptions()
-    slug: getsubscriptions
-    product: 'realtime'
-
-  - id: get-channels
-    title: getChannels()
-    slug: getchannels
-    product: 'realtime'
-
-  - id: remove-channel
-    title: removeChannel()
-    slug: removechannel
-    product: 'realtime'
-
-  - id: remove-all-channels
-    title: removeAllChannels()
-    slug: removeallchannels
-    product: 'realtime'
-
-  - id: list-buckets
-    title: listBuckets()
-    slug: storage-listbuckets
-    product: 'storage'
-
-  - id: get-bucket
-    title: getBucket()
-    slug: storage-getbucket
-    product: 'storage'
-
-  - id: create-bucket
-    title: createBucket()
-    slug: storage-createbucket
-    product: 'storage'
-
-  - id: empty-bucket
-    title: emptyBucket()
-    slug: storage-emptybucket
-    product: 'storage'
-
-  - id: update-bucket
-    title: updateBucket()
-    slug: storage-updatebucket
-    product: 'storage'
-
-  - id: delete-bucket
-    title: deleteBucket()
-    slug: storage-deletebucket
-    product: 'storage'
-
-  - id: from-upload
-    title: from.upload()
-    slug: storage-from-upload
-    product: 'storage'
-
-  - id: from-update
-    title: from.update()
-    slug: storage-from-update
-    product: 'storage'
-
-  - id: from-move
-    title: from.move()
-    slug: storage-from-move
-    product: 'storage'
-
-  - id: from-copy
-    title: from.copy()
-    slug: storage-from-copy
-    product: 'storage'
-
-  - id: from-create-signed-url
-    title: from.createSignedUrl()
-    slug: storage-from-createsignedurl
-    product: 'storage'
-
-  - id: from-create-signed-urls
-    title: from.createSignedUrls()
-    slug: storage-from-createsignedurls
-    product: 'storage'
-
-  - id: from-get-public-url
-    title: from.getPublicUrl()
-    slug: storage-from-getpublicurl
-    product: 'storage'
-
-  - id: from-download
-    title: from.download()
-    slug: storage-from-download
-    product: 'storage'
-
-  - id: from-remove
-    title: from.remove()
-    slug: storage-from-remove
-    product: 'storage'
-
-  - id: from-list
-    title: from.list()
-    slug: storage-from-list
-    product: 'storage'