Skip to content

Commit 706b4a4

Browse files
devalogdevalog
authored
Expand README guide (SDKs) (#778)
1 parent ae87e3f commit 706b4a4

File tree

3 files changed

+77
-87
lines changed

3 files changed

+77
-87
lines changed

‎fern/products/sdks/guides/configure-readme.mdx‎

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,13 @@ title: Customize README
33
description: Guide to configuring the README in your SDK
44
---
55

6-
By default, the README for your SDKs is generated programmatically. You can override this by configuring the `readme` section in `generators.yml` to control the content and structure of generated README files across all your SDKs.
7-
You can add custom introductions, showcase key endpoints, and organize your SDK documentation with feature sections.
6+
By default, the README for your SDKs is generated programmatically. You can customize the content and structure of these README files across all of your SDKs by configuring the `readme` section in `generators.yml`.
87

9-
```yaml title="generators.yml"
10-
readme:
11-
introduction: "Welcome to our API"
12-
apiReferenceLink: "https://docs.example.com"
13-
apiName: "Example Product"
14-
disabledSections:
15-
- "contributing"
16-
defaultEndpoint:
17-
method: "POST"
18-
path: "/users"
19-
features:
20-
authentication:
21-
- method: "POST"
22-
path: "/auth/login"
23-
users:
24-
- method: "GET"
25-
path: "/users"
26-
```
278

28-
For more detailed information on `readme` configuration, see the [`generators.yml` documentation](/sdks/reference/generators-yml#readme)
9+
## Configuration options
10+
11+
<Markdown src="/products/sdks/snippets/readme-options.mdx" />
12+
13+
## Additional customization
14+
15+
For customization beyond these configuration options, you can [manually modify the README](/products/sdks/custom-code.mdx) and add it to your `.fernignore` file to prevent it from being overwritten during regeneration.

‎fern/products/sdks/reference/generators-yml-reference.mdx‎

Lines changed: 2 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -330,74 +330,10 @@ metadata:
330330
</ParamField>
331331

332332
## readme
333-
Controls what goes into the generated README files across all SDKs, allowing you to customize the content and structure of your SDK documentation.
334-
335-
```yaml
336-
readme:
337-
bannerLink: "https://example.com/banner"
338-
introduction: "Welcome to our API"
339-
apiReferenceLink: "https://docs.example.com"
340-
apiName: "Example Product"
341-
disabledSections:
342-
- "contributing"
343-
defaultEndpoint:
344-
method: "POST"
345-
path: "/users"
346-
stream: false
347-
features:
348-
authentication:
349-
- method: "POST"
350-
path: "/auth/login"
351-
- "GET /auth/profile"
352-
users:
353-
- method: "GET"
354-
path: "/users"
355-
- method: "POST"
356-
path: "/users"
357-
```
358-
359-
<ParamField path="bannerLink" type="string" required={false} toc={true}>
360-
URL for a banner image or link that appears at the top of the README.
361-
</ParamField>
362-
363-
<ParamField path="introduction" type="string" required={false} toc={true}>
364-
Custom introduction text that appears at the beginning of the README.
365-
</ParamField>
366-
367-
<ParamField path="apiReferenceLink" type="string" required={false} toc={true}>
368-
URL to your external API documentation or reference guide.
369-
</ParamField>
370-
371-
<ParamField path="apiName" type="string" required={false} toc={true}>
372-
Name of the API that appears in the README. Will appear as `Your Api Name SDK` or `Your Api Name API` throughout the README. Defaults to organization name if not set.
373-
</ParamField>
374-
375-
<ParamField path="disabledSections" type="string[]" required={false} toc={true}>
376-
Sections to disable in the README. Supported values: `"contributing"`.
377-
</ParamField>
378-
379-
<ParamField path="defaultEndpoint" type="ReadmeEndpointSchema" required={false} toc={true}>
380-
Specifies which endpoint's code snippet to showcase as the primary example in the README.
381-
</ParamField>
382-
383-
<ParamField path="features" type="map<string, list<ReadmeEndpointSchema>>" required={false} toc={true}>
384-
Groups endpoints by feature name for organized README sections. Each feature becomes a section in the README with example code snippets for the listed endpoints.
385-
</ParamField>
386-
387-
### defaultEndpoint
388-
Specifies which endpoint's code snippet to showcase as the primary example in the README.
389-
390-
<ParamField path="method" type="string" required={true} toc={true}>
391-
HTTP method of the default endpoint (e.g., `GET`, `POST`, `PUT`, `DELETE`).
392-
</ParamField>
393333

394-
<ParamField path="path" type="string" required={true} toc={true}>
395-
Endpoint path for the default example (e.g., `/users`, `/auth/login`).
396-
</ParamField>
334+
Controls what goes into the generated README files across all SDKs, allowing you to customize the content and structure of your SDK documentation.
397335

398-
<ParamField path="stream" type="boolean" required={false} default="false" toc={true}>
399-
Whether the endpoint is a streaming endpoint. Defaults to `false`.
400-
</ParamField>
336+
<Markdown src="/products/sdks/snippets/readme-options.mdx" />
401337

402338
## default-group
403339
Which group to use when none is specified.

‎fern/products/sdks/snippets/readme-options.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
```yaml
2+
readme:
3+
bannerLink: "https://example.com/banner"
4+
introduction: "Welcome to our API"
5+
apiReferenceLink: "https://docs.example.com"
6+
apiName: "Example Product"
7+
disabledSections:
8+
- "contributing"
9+
defaultEndpoint:
10+
method: "POST"
11+
path: "/users"
12+
stream: false
13+
features:
14+
authentication:
15+
- method: "POST"
16+
path: "/auth/login"
17+
- "GET /auth/profile"
18+
users:
19+
- method: "GET"
20+
path: "/users"
21+
- method: "POST"
22+
path: "/users"
23+
```
24+
25+
<ParamField path="bannerLink" type="string" required={false} toc={true}>
26+
URL for a banner image or link that appears at the top of the README.
27+
</ParamField>
28+
29+
<ParamField path="introduction" type="string" required={false} toc={true}>
30+
Custom introduction text that appears at the beginning of the README.
31+
</ParamField>
32+
33+
<ParamField path="apiReferenceLink" type="string" required={false} toc={true}>
34+
URL to your external API documentation or reference guide.
35+
</ParamField>
36+
37+
<ParamField path="apiName" type="string" required={false} toc={true}>
38+
Name of the API that appears in the README. Will appear as `Your Api Name SDK` or `Your Api Name API` throughout the README. Defaults to organization name if not set.
39+
</ParamField>
40+
41+
<ParamField path="disabledSections" type="string[]" required={false} toc={true}>
42+
Sections to disable in the README. Supported values: `"contributing"`.
43+
</ParamField>
44+
45+
<ParamField path="defaultEndpoint" type="ReadmeEndpointSchema" required={false} toc={true}>
46+
Specifies which endpoint's code snippet to showcase as the primary example in the README.
47+
</ParamField>
48+
49+
<ParamField path="features" type="map<string, list<ReadmeEndpointSchema>>" required={false} toc={true}>
50+
Organizes endpoints into named feature sections within the README. Each feature creates a dedicated section with example code snippets for the specified endpoints.
51+
</ParamField>
52+
53+
### Endpoint configuration
54+
55+
Specifies which endpoint's code snippet to showcase as the primary example in the README.
56+
57+
<ParamField path="defaultEndpoint.method" type="string" required={true} toc={true}>
58+
HTTP method of the default endpoint (e.g., `GET`, `POST`, `PUT`, `DELETE`).
59+
</ParamField>
60+
61+
<ParamField path="defaultEndpoint.path" type="string" required={true} toc={true}>
62+
Endpoint path for the default example (e.g., `/users`, `/auth/login`).
63+
</ParamField>
64+
65+
<ParamField path="defaultEndpoint.stream" type="boolean" required={false} default="false" toc={true}>
66+
Whether the endpoint is a streaming endpoint. Defaults to `false`.
67+
</ParamField>

0 commit comments

Comments
 (0)