Skip to content

Commit 6c36a91

Browse files
devalogdevalog
committed
readme updates draft
1 parent 0ac8f0c commit 6c36a91

File tree

3 files changed

+74
-85
lines changed

3 files changed

+74
-85
lines changed

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

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,10 @@ description: Guide to configuring the README in your SDK
66
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.
77
You can add custom introductions, showcase key endpoints, and organize your SDK documentation with feature sections.
88

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-
```
9+
## Configuration options
2710

28-
For more detailed information on `readme` configuration, see the [`generators.yml` documentation](/sdks/reference/generators-yml#readme)
11+
<Markdown src="/products/sdks/snippets/readme-options.mdx" />
12+
13+
## Additional customization
14+
15+
If you want to customize the README further than the allowed configuration options, you can [manually modify the readme](/products/sdks/custom-code.mdx), then add it to your `.fernignore` file so it doesn't get overwritten on regenerations.

‎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: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
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+
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.
51+
</ParamField>
52+
53+
### defaultEndpoint
54+
Specifies which endpoint's code snippet to showcase as the primary example in the README.
55+
56+
<ParamField path="method" type="string" required={true} toc={true}>
57+
HTTP method of the default endpoint (e.g., `GET`, `POST`, `PUT`, `DELETE`).
58+
</ParamField>
59+
60+
<ParamField path="path" type="string" required={true} toc={true}>
61+
Endpoint path for the default example (e.g., `/users`, `/auth/login`).
62+
</ParamField>
63+
64+
<ParamField path="stream" type="boolean" required={false} default="false" toc={true}>
65+
Whether the endpoint is a streaming endpoint. Defaults to `false`.
66+
</ParamField>

0 commit comments

Comments
 (0)