diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 01972d4..e10b962 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -12,7 +12,7 @@ jobs: strategy: fail-fast: false matrix: - project: [docs-starter, graphql, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning] + project: [docs-starter, graphql, grpc, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning] steps: - name: Checkout repository uses: actions/checkout@v4 diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml index dc13a0c..170bd75 100644 --- a/.github/workflows/preview-docs.yml +++ b/.github/workflows/preview-docs.yml @@ -31,7 +31,7 @@ jobs: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }} run: | - PROJECTS="docs-starter graphql i18n multi-source/homepage multi-source/seeds multi-source/seeds-sunflower multi-source/seeds-tomato multi-source/greenhouses multi-source/nursery versioning" + PROJECTS="docs-starter graphql grpc i18n multi-source/homepage multi-source/seeds multi-source/seeds-sunflower multi-source/seeds-tomato multi-source/greenhouses multi-source/nursery versioning" CHANGED_FILES=$(git diff --name-only origin/main...HEAD) : > comment.md diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index a7895c3..0880c5d 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -12,7 +12,7 @@ jobs: strategy: fail-fast: false matrix: - project: [docs-starter, graphql, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning] + project: [docs-starter, graphql, grpc, i18n, multi-source/homepage, multi-source/seeds, multi-source/seeds-sunflower, multi-source/seeds-tomato, multi-source/greenhouses, multi-source/nursery, versioning] steps: - name: Checkout repository uses: actions/checkout@v4 diff --git a/README.md b/README.md index 2cbb183..c874970 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Example Fern docs projects. Each top-level folder is a self-contained example wi | --- | --- | --- | | [`docs-starter`](./docs-starter) | Minimal starter project | [docs-starter.docs.buildwithfern.com](https://docs-starter.docs.buildwithfern.com) | | [`graphql`](./graphql) | GraphQL API Reference from a `.graphql` schema | [graphql.docs.buildwithfern.com](https://graphql.docs.buildwithfern.com) | +| [`grpc`](./grpc) | gRPC API Reference from `.proto` files | [grpc.docs.buildwithfern.com](https://grpc.docs.buildwithfern.com) | | [`i18n`](./i18n) | Multi-language docs with English + Japanese translations | [i18n.docs.buildwithfern.com](https://i18n.docs.buildwithfern.com) | | [`multi-source`](./multi-source) | Multi-source docs — six independent projects publishing to one domain with global theme, nested sub-paths, and shared branding | [multi-source.docs.buildwithfern.com](https://multi-source.docs.buildwithfern.com) | | [`versioning`](./docs-versioned) | Versioned site with a version dropdown and a shared page | [versioning.docs.buildwithfern.com](https://versioning.docs.buildwithfern.com) | diff --git a/grpc/fern/docs.yml b/grpc/fern/docs.yml new file mode 100644 index 0000000..bfc9973 --- /dev/null +++ b/grpc/fern/docs.yml @@ -0,0 +1,69 @@ +# yaml-language-server: $schema=https://schema.buildwithfern.dev/docs-yml.json + +instances: + - url: grpc.docs.buildwithfern.com + +title: gRPC Docs Example + +layout: + searchbar-placement: header + page-width: full + tabs-placement: header + +tabs: + home: + display-name: Docs + icon: home + API Reference: + display-name: API Reference + icon: puzzle + +navigation: + - tab: home + layout: + - section: Get started + contents: + - page: Welcome + path: docs/pages/welcome.mdx + icon: fa-duotone fa-house + - tab: API Reference + layout: + - section: Overview + contents: + - page: API reference + path: docs/pages/api-reference-overview.mdx + icon: fa-duotone fa-book + - api: Plant Store gRPC API + flattened: true + +navbar-links: + - type: minimal + text: Fork this repo + url: https://github.com/fern-api/docs-examples + - type: filled + text: Dashboard + url: https://dashboard.buildwithfern.com + - type: github + value: https://github.com/fern-api/fern + +colors: + accent-primary: + dark: "#70E155" + light: "#008700" + background: + dark: "#111113" + light: "#FFFFFF" + +theme: + page-actions: toolbar + footer-nav: minimal + +logo: + dark: docs/assets/logo-dark.svg + light: docs/assets/logo.svg + height: 20 + href: https://buildwithfern.com + +favicon: docs/assets/favicon.svg + +css: styles.css diff --git a/grpc/fern/docs/assets/favicon.svg b/grpc/fern/docs/assets/favicon.svg new file mode 100644 index 0000000..568bb7e --- /dev/null +++ b/grpc/fern/docs/assets/favicon.svg @@ -0,0 +1,8 @@ + + + + \ No newline at end of file diff --git a/grpc/fern/docs/assets/fern-logo-primary.svg b/grpc/fern/docs/assets/fern-logo-primary.svg new file mode 100644 index 0000000..a21927d --- /dev/null +++ b/grpc/fern/docs/assets/fern-logo-primary.svg @@ -0,0 +1,4 @@ + + + + diff --git a/grpc/fern/docs/assets/fern-logo-white.svg b/grpc/fern/docs/assets/fern-logo-white.svg new file mode 100644 index 0000000..9dd77b1 --- /dev/null +++ b/grpc/fern/docs/assets/fern-logo-white.svg @@ -0,0 +1,4 @@ + + + + diff --git a/grpc/fern/docs/assets/logo-dark.svg b/grpc/fern/docs/assets/logo-dark.svg new file mode 100644 index 0000000..144e0e3 --- /dev/null +++ b/grpc/fern/docs/assets/logo-dark.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/grpc/fern/docs/assets/logo-light.svg b/grpc/fern/docs/assets/logo-light.svg new file mode 100644 index 0000000..7cf2ee2 --- /dev/null +++ b/grpc/fern/docs/assets/logo-light.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/grpc/fern/docs/assets/logo.svg b/grpc/fern/docs/assets/logo.svg new file mode 100644 index 0000000..2d280fe --- /dev/null +++ b/grpc/fern/docs/assets/logo.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/grpc/fern/docs/pages/api-reference-overview.mdx b/grpc/fern/docs/pages/api-reference-overview.mdx new file mode 100644 index 0000000..1b809bc --- /dev/null +++ b/grpc/fern/docs/pages/api-reference-overview.mdx @@ -0,0 +1,22 @@ +--- +title: API reference +subtitle: Interactive documentation generated from Protocol Buffer files +slug: api-reference +--- + +Fern generates interactive API Reference documentation from your `.proto` files. This example uses a sample Plant Store gRPC API to demonstrate the feature. + +The generated reference includes all services, RPCs, messages, and enums with field-level documentation pulled from your proto comments. + +## Plant Store gRPC API + +Browse the API endpoints in the sidebar, or jump to a section: + + + + Request-response operations for plants and orders + + + Real-time server-streaming updates + + diff --git a/grpc/fern/docs/pages/welcome.mdx b/grpc/fern/docs/pages/welcome.mdx new file mode 100644 index 0000000..b8485a2 --- /dev/null +++ b/grpc/fern/docs/pages/welcome.mdx @@ -0,0 +1,28 @@ +--- +title: gRPC docs example +subtitle: Generate API Reference documentation from Protocol Buffer files +slug: welcome +--- + +This example shows how [Fern](https://buildwithfern.com) generates interactive API Reference documentation from Protocol Buffer (`.proto`) files. It uses a sample Plant Store gRPC API with unary RPCs and server-streaming. + +Navigate to the [API Reference](/api-reference) tab to see the generated documentation. + +## What's included + + + + + + + + + + + + + + +## Learn more + +For configuration details, see the [gRPC Reference documentation](https://buildwithfern.com/learn/docs/api-references/generate-grpc-ref). diff --git a/grpc/fern/fern.config.json b/grpc/fern/fern.config.json new file mode 100644 index 0000000..9f41ff5 --- /dev/null +++ b/grpc/fern/fern.config.json @@ -0,0 +1,4 @@ +{ + "organization": "fern-docs-examples", + "version": "5.35.0" +} diff --git a/grpc/fern/generators.yml b/grpc/fern/generators.yml new file mode 100644 index 0000000..f1f99f2 --- /dev/null +++ b/grpc/fern/generators.yml @@ -0,0 +1,6 @@ +# yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json +api: + specs: + - proto: + root: ./proto + target: proto/plantstore/v1/plantstore.proto diff --git a/grpc/fern/proto/plantstore/v1/plantstore.proto b/grpc/fern/proto/plantstore/v1/plantstore.proto new file mode 100644 index 0000000..865a571 --- /dev/null +++ b/grpc/fern/proto/plantstore/v1/plantstore.proto @@ -0,0 +1,199 @@ +syntax = "proto3"; + +package plantstore.v1; + +import "google/protobuf/timestamp.proto"; + +// The Plant Store service manages a catalog of plants and customer orders. +service PlantStoreService { + // Look up a plant by its ID. + rpc GetPlant(GetPlantRequest) returns (Plant); + + // List plants with optional filtering. + rpc ListPlants(ListPlantsRequest) returns (ListPlantsResponse); + + // Add a new plant to the catalog. + rpc CreatePlant(CreatePlantRequest) returns (Plant); + + // Remove a plant from the catalog. + rpc DeletePlant(DeletePlantRequest) returns (DeletePlantResponse); + + // Look up an order by its ID. + rpc GetOrder(GetOrderRequest) returns (Order); + + // List orders, optionally filtered by status. + rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse); + + // Place a new order. + rpc PlaceOrder(PlaceOrderRequest) returns (Order); + + // Update an order's status. + rpc UpdateOrderStatus(UpdateOrderStatusRequest) returns (Order); + + // Stream real-time order status updates. + rpc WatchOrderStatus(WatchOrderStatusRequest) returns (stream OrderStatusEvent); +} + +// Care difficulty levels. +enum Difficulty { + DIFFICULTY_UNSPECIFIED = 0; + // Minimal care required. + DIFFICULTY_EASY = 1; + // Some gardening experience helpful. + DIFFICULTY_MODERATE = 2; + // Requires specific conditions and attention. + DIFFICULTY_HARD = 3; +} + +// Order lifecycle statuses. +enum OrderStatus { + ORDER_STATUS_UNSPECIFIED = 0; + ORDER_STATUS_PENDING = 1; + ORDER_STATUS_CONFIRMED = 2; + ORDER_STATUS_SHIPPED = 3; + ORDER_STATUS_DELIVERED = 4; + ORDER_STATUS_CANCELLED = 5; +} + +// A plant in the catalog. +message Plant { + // Unique identifier for the plant. + string id = 1; + // Common name of the plant. + string name = 2; + // Botanical (Latin) name. + string species = 3; + // Care difficulty rating. + Difficulty difficulty = 4; + // Whether the plant is currently in stock. + bool in_stock = 5; + // Price in USD cents. + int32 price_in_cents = 6; + // Tags describing the plant. + repeated string tags = 7; + // When the plant was added to the catalog. + google.protobuf.Timestamp created_at = 8; +} + +// A customer order. +message Order { + // Unique identifier for the order. + string id = 1; + // Items included in the order. + repeated OrderItem items = 2; + // Current status of the order. + OrderStatus status = 3; + // When the order was placed. + google.protobuf.Timestamp placed_at = 4; +} + +// A single line item in an order. +message OrderItem { + // The ID of the plant being ordered. + string plant_id = 1; + // Number of units. + int32 quantity = 2; +} + +// Request to get a single plant. +message GetPlantRequest { + // ID of the plant to retrieve. + string id = 1; +} + +// Request to list plants. +message ListPlantsRequest { + // Filter by difficulty level. + Difficulty difficulty = 1; + // Only show plants that are in stock. + bool in_stock_only = 2; + // Filter by tag. + string tag = 3; + // Maximum number of results to return. + int32 limit = 4; + // Number of results to skip. + int32 offset = 5; +} + +// Response containing a list of plants. +message ListPlantsResponse { + // The list of plants matching the filter. + repeated Plant plants = 1; + // Total number of plants matching the filter. + int32 total_count = 2; +} + +// Request to create a new plant. +message CreatePlantRequest { + // Common name of the plant. + string name = 1; + // Botanical (Latin) name. + string species = 2; + // Care difficulty rating. + Difficulty difficulty = 3; + // Price in USD cents. + int32 price_in_cents = 4; + // Tags describing the plant. + repeated string tags = 5; +} + +// Request to delete a plant. +message DeletePlantRequest { + // ID of the plant to delete. + string id = 1; +} + +// Response from deleting a plant. +message DeletePlantResponse {} + +// Request to get a single order. +message GetOrderRequest { + // ID of the order to retrieve. + string id = 1; +} + +// Request to list orders. +message ListOrdersRequest { + // Filter by order status. + OrderStatus status = 1; + // Maximum number of results to return. + int32 limit = 2; +} + +// Response containing a list of orders. +message ListOrdersResponse { + // The list of orders matching the filter. + repeated Order orders = 1; +} + +// Request to place a new order. +message PlaceOrderRequest { + // Items to include in the order. + repeated OrderItem items = 1; +} + +// Request to update an order's status. +message UpdateOrderStatusRequest { + // ID of the order to update. + string id = 1; + // New status for the order. + OrderStatus status = 2; +} + +// Request to watch order status changes. +message WatchOrderStatusRequest { + // ID of the order to watch. + string order_id = 1; +} + +// An order status change event. +message OrderStatusEvent { + // ID of the order. + string order_id = 1; + // Previous status. + OrderStatus previous_status = 2; + // New status. + OrderStatus new_status = 3; + // When the status changed. + google.protobuf.Timestamp changed_at = 4; +} diff --git a/grpc/fern/styles.css b/grpc/fern/styles.css new file mode 100644 index 0000000..154c7a8 --- /dev/null +++ b/grpc/fern/styles.css @@ -0,0 +1,10 @@ +/* Custom styles for Fern Docs Starter */ + +/* Subtle linear gradient background */ +.fern-background-image { + background-image: linear-gradient(180deg, rgba(0, 135, 0, 0.03) 0%, transparent 50%); +} + +:root.dark .fern-background-image { + background-image: linear-gradient(180deg, rgba(112, 225, 85, 0.03) 0%, transparent 50%); +}