add docs for metadata generation (#645)

Co-authored-by: Rob Dominguez <[email protected]>

docs/project-configuration/metadata-generation.mdx

@@ -0,0 +1,134 @@
+---
+sidebar_position: 10
+sidebar_label: Generating metadata
+description:
+  "Learn about generating metadata and customizing it using the DDN CLI"
+keywords:
+  - hasura ddn
+  - hasura cli
+  - local dev
+  - metadata generation
+seoFrontMatterUpdated: false
+---
+
+# Generating metadata
+
+## Introduction
+
+The DDN CLI can auto-generate metadata for your supergraph based on the schema of the sources added via
+[data connectors](/connectors/overview.mdx). You can also manually edit the metadata using an editor.
+
+The [Supergraph modeling](/supergraph-modeling/overview.mdx) section has details of the various metadata objects that
+make up your supergraph.
+
+## Generating metadata
+
+### Using the CLI
+
+Once you have [configured your supergraph](/getting-started/quickstart.mdx) and added a connector, you would typically
+use the following commands on a day-to-day basis to generate and update the supergraph metadata based on the schema of
+your data source:
+
+- **Step 1:** Introspect the data source and update the connector schema:
+  ```bash
+  ddn connector introspect <connector-name>
+  ```
+  This will update the connector configuration based on the data source and update the connector schema in the
+  corresponding [DataConnectorLink](/supergraph-modeling/data-connector-links.mdx).
+
+- **Step 2:** Add models, commands and relationships from the connector schema:
+  ```bash
+  ddn model add <connector-name> "*"
+  ddn command add <connector-name> "*"
+  ddn relationship add <connector-name> "*"
+  ```
+
+  This will create and update metadata objects for the entities in your data source to expose them via the GraphQL API.
+
+  :::info
+
+  The CLI generates metadata objects based on the [generator config](#subgraph-generator-config) defined in the
+  subgraph config file.
+
+  :::
+
+
+-  You can then build the supergraph with the new metadata to run with the local engine:
+   ```bash
+   ddn supergraph build local
+   ddn run docker-start
+   ```
+
+### Using an editor
+
+You can also manually add or update the metadata objects using an editor. The [Hasura VS code extension](https://marketplace.visualstudio.com/items?itemName=HasuraHQ.hasura)
+assists with authoring metadata manually.
+
+As mentioned in the previous section you would typically use the CLI to generate most of your metadata. That being said
+you would typically need to manually edit metadata to define [permissions](/supergraph-modeling/permissions.mdx) and
+[relationships](/supergraph-modeling/relationships.mdx) or to customize the metadata auto-generated by the CLI, e.g. to
+modify descriptions, graphql field names, etc.
+
+## Subgraph generator config {#subgraph-generator-config}
+
+The configuration for generating metadata for a subgraph is defined in the `generator` field of the subgraph config file
+of the subgraph.
+
+For example,
+
+```yaml title="app/subgraph.yaml"
+kind: Subgraph
+version: v2
+definition:
+  name: app
+  #highlight-start
+  generator:
+    rootPath: .
+    graphqlRootFieldPrefix: app_
+    graphqlTypeNamePrefix: App_
+    namingConvention: graphql
+  #highlight-end
+  includePaths:
+    - metadata
+  envMapping:
+    ...
+```
+
+The following are the supported configuration options:
+
+### rootPath
+
+Defines the directory in which new metadata files are generated. Metadata is generated in the `/metadata` directory in
+the defined root path. It is defined relative to the subgraph config file.
+
+**Default**: `.` i.e. metadata is generated in the `<subgraph-name>/metadata` directory
+
+### graphqlRootFieldPrefix
+
+Defines the prefix to add to all GraphQL root fields generated for models and commands in the subgraph.
+
+**Default**: `""` i.e. no prefix is added by default
+
+Also see: [Rename GraphQL prefixes command](/cli/commands/ddn_codemod_rename-graphql-prefixes)
+
+### graphqlTypeNamePrefix
+
+Defines the prefix to add to all GraphQL types generated for models and commands in the subgraph.
+
+**Default**: `""` i.e. no prefix is added by default
+
+Also see: [Rename GraphQL prefixes command](/cli/commands/ddn_codemod_rename-graphql-prefixes)
+
+### namingConvention
+
+Defines the naming convention used while generating GraphQL types and root fields generated for models and commands in
+the subgraph.
+
+**Default**: `graphql`
+
+The following are the supported values:
+
+| Convention | Description                                                                                                                        |
+|------------|------------------------------------------------------------------------------------------------------------------------------------|
+| `graphql`  | Convert the identifier from the data source to the GraphQL naming convention. i.e. PascalCase for types, camelCase for root fields |
+| `none`     | Use the identifier from the data source as is.                                                                                     |