Skip to content

Commit ebcf9de

Browse files
devalogdevalog
authored
Add mode info to PyPi Publishing doc, restructure for clarity (SDKs) (#754)
1 parent 47f7252 commit ebcf9de

File tree

5 files changed

+143
-115
lines changed

5 files changed

+143
-115
lines changed

‎examples/sdks/generators.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ groups:
2222
namespaceExport: YourClientName
2323
github:
2424
repository: your-company/ts-sdk
25+
mode: push
26+
branch: your-branch-name
2527
# This group configures a Python SDK for PyPi publishing
2628
python-sdk:
2729
generators:
@@ -35,4 +37,5 @@ groups:
3537
client_class_name: MyClientNameDevin
3638
github:
3739
repository: devalog/company-python-test
40+
mode: pull-request
3841
# generator groups for other SDKs go here

‎fern/products/sdks/overview/python/publishing-to-pypi.mdx‎

Lines changed: 126 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,28 @@ you'll have a versioned package published on PyPI.
1111
<img src="assets/pypi-package.png" alt="Versioned package published on PyPI" />
1212
</Frame>
1313

14-
<Markdown src="/products/sdks/snippets/setup-fern-folder-callout.mdx"/>
14+
<Info>
15+
This page assumes that you have:
1516

16-
## Configure `generators.yml`
17+
* An initialized `fern` folder. See [Set up the `fern`
18+
folder](/sdks/overview/quickstart).
19+
* A GitHub repository for your Python SDK. See [Project structure](/sdks/overview/project-structure).
20+
* A Python generator group in `generators.yml`. See [Python
21+
Quickstart](quickstart#add-the-sdk-generator).
22+
23+
</Info>
24+
25+
## Configure SDK package settings
26+
27+
You'll need to update your `generators.yml` file to configure the package name, output location, and client naming for PyPi publishing. Your `generators.yml` [should live in your source repository](/sdks/overview/project-structure) (or on your local machine), not the repository that contains your Python SDK code.
1728

1829
<Steps>
1930

2031
<Step title="Configure `output` location">
2132

22-
Next, change the output location in `generators.yml` from `local-file-system` (the default) to `pypi` to indicate that Fern should publish your package directly to the PyPI registry:
33+
In the `group` for your Python SDK, change the output location in from `local-file-system` (the default) to `pypi` to indicate that Fern should publish your package directly to the PyPi registry:
2334

24-
```yaml title="Python" {6-7}
35+
```yaml title="generators.yml" {6-7}
2536
groups:
2637
python-sdk:
2738
generators:
@@ -35,10 +46,10 @@ you'll have a versioned package published on PyPI.
3546

3647
<Step title="Add a unique package name">
3748

38-
Your package name must be unique in the PyPI repository, otherwise publishing your SDK to PyPI will fail. Update your package name if you haven't done so already:
49+
Your package name must be unique in the PyPI repository, otherwise publishing your SDK to PyPI will fail.
3950

4051

41-
```yaml title="Python" {8}
52+
```yaml title="generators.yml" {8}
4253
groups:
4354
python-sdk:
4455
generators:
@@ -56,7 +67,7 @@ groups:
5667
The `client-class-name` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`).
5768

5869

59-
```yaml title="Python" {9-10}
70+
```yaml title="generators.yml" {9-10}
6071
groups:
6172
python-sdk:
6273
generators:
@@ -70,30 +81,9 @@ groups:
7081
```
7182
7283
</Step>
73-
74-
<Step title="Add repository location">
75-
76-
Add the path to your GitHub repository to `generators.yml`:
77-
78-
```yaml title="Python" {11-12}
79-
groups:
80-
python-sdk:
81-
generators:
82-
- name: fernapi/fern-python-sdk
83-
version: <Markdown src="/snippets/version-number-python.mdx"/>
84-
output:
85-
location: pypi
86-
package-name: your-package-name
87-
config:
88-
client_class_name: YourClientName
89-
github:
90-
repository: your-org/company-python
91-
```
92-
93-
</Step>
9484
</Steps>
9585

96-
## Set up PyPi publishing authentication
86+
## Generate a PyPi token
9787

9888
<Steps>
9989

@@ -127,53 +117,34 @@ groups:
127117

128118
</Steps>
129119

130-
## Release your SDK to PyPI
131-
132-
At this point, you're ready to generate a release for your SDK.
133-
<AccordionGroup>
134-
<Accordion title="Release via a GitHub workflow (recommended)">
135-
136-
Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository.
120+
## Configure PyPi publication
137121

138122
<Steps>
139-
<Step title="Set up authentication">
140-
141-
Open your Fern repository in GitHub. Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.
142-
143-
<Frame>
144-
<img src="assets/github-secret.png" alt="Adding GitHub Repository Secret" />
145-
</Frame>
123+
<Step title="Add repository location">
146124

147-
You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.
148-
149-
</Step>
150-
<Step title="Add secret for your PyPi Token">
151-
152-
1. Select **New repository secret**.
153-
1. Name your secret `PYPI_TOKEN`.
154-
1. Add the corresponding token you generated above.
155-
1. Click **Add secret**.
156-
157-
<Frame>
158-
<img src="assets/pypi-token-secret.png" alt="PYPI_TOKEN secret" />
159-
</Frame>
125+
Add the path to your GitHub repository to `generators.yml`:
160126

161-
</Step>
162-
<Step title="Add secret for your Fern Token">
163-
164-
1. Select **New repository secret**.
165-
1. Name your secret `FERN_TOKEN`.
166-
1. Add your Fern token. If you don't already have one, generate one by
167-
running `fern token`. By default, the `fern_token` is generated for the
168-
organization listed in `fern.config.json`.
169-
1. Click **Add secret**.
170-
171-
</Step>
172-
<Step title="Configure PyPi authentication token">
127+
```yaml title="generators.yml" {11-12}
128+
groups:
129+
python-sdk:
130+
generators:
131+
- name: fernapi/fern-python-sdk
132+
version: <Markdown src="/snippets/version-number-python.mdx"/>
133+
output:
134+
location: pypi
135+
package-name: your-package-name
136+
config:
137+
client_class_name: YourClientName
138+
github:
139+
repository: your-org/company-python
140+
```
141+
142+
</Step>
143+
<Step title="Configure PyPi authentication token">
173144

174-
Add `token: ${PYPI_TOKEN}` to `generators.yml`.
145+
Add `token: ${PYPI_TOKEN}` to `generators.yml`.
175146

176-
```yaml {9} title="generators.yml"
147+
```yaml {9} title="generators.yml"
177148
groups:
178149
python-sdk:
179150
generators:
@@ -187,11 +158,81 @@ groups:
187158
client_class_name: YourClientName
188159
github:
189160
repository: your-org/company-python
190-
```
191-
</Step>
192-
<Step title="Set up a new workflow">
161+
```
162+
</Step>
163+
<Step title="Choose your publishing mode">
164+
165+
<Markdown src="/products/sdks/snippets/github-publishing-mode.mdx"/>
166+
167+
```yaml title="generators.yml" {14}
168+
groups:
169+
python-sdk:
170+
generators:
171+
- name: fernapi/fern-python-sdk
172+
version: <Markdown src="/snippets/version-number-python.mdx"/>
173+
output:
174+
location: npm
175+
package-name: name-of-your-package
176+
token: ${PYPI_TOKEN}
177+
config:
178+
namespaceExport: YourClientName
179+
github:
180+
repository: your-org/your-repository
181+
mode: push
182+
branch: your-branch-name # Required for mode: push
183+
```
184+
185+
</Step>
186+
</Steps>
187+
188+
## Publish your SDK
193189

194-
Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this:
190+
Decide how you want to publish your SDK to PyPi. You can use GitHub workflows for automated releases or publish directly via the CLI.
191+
192+
<AccordionGroup>
193+
<Accordion title="Release via a GitHub workflow (recommended)">
194+
195+
Set up a release workflow via [GitHub Actions](https://docs.github.com/en/actions/get-started/quickstart) so you can trigger new SDK releases directly from your source repository.
196+
197+
<Steps>
198+
199+
<Step title="Set up authentication">
200+
201+
Open your Fern repository in GitHub. Click on the **Settings** tab in your repository. Then, under the **Security** section, open **Secrets and variables** > **Actions**.
202+
203+
<Frame>
204+
<img src="assets/github-secret.png" alt="Adding GitHub Repository Secret" />
205+
</Frame>
206+
207+
You can also use the url `https://github.com/<your-repo>/settings/secrets/actions`.
208+
209+
</Step>
210+
<Step title="Add secret for your PyPi Token">
211+
212+
1. Select **New repository secret**.
213+
1. Name your secret `PYPI_TOKEN`.
214+
1. Add the corresponding token you generated above.
215+
1. Click **Add secret**.
216+
217+
<Frame>
218+
<img src="assets/pypi-token-secret.png" alt="PYPI_TOKEN secret" />
219+
</Frame>
220+
221+
</Step>
222+
<Step title="Add secret for your Fern Token">
223+
224+
1. Select **New repository secret**.
225+
1. Name your secret `FERN_TOKEN`.
226+
1. Add your Fern token. If you don't already have one, generate one by
227+
running `fern token`. By default, the `fern_token` is generated for the
228+
organization listed in `fern.config.json`.
229+
1. Click **Add secret**.
230+
231+
</Step>
232+
233+
<Step title="Set up a new workflow">
234+
235+
Set up a CI workflow that you can manually trigger from the GitHub UI. In your repository, navigate to **Actions**. Select **New workflow**, then **Set up workflow yourself**. Add a workflow that's similar to this:
195236

196237
```yaml title=".github/workflows/publish.yml" maxLines=0
197238
name: Publish Python SDK
@@ -222,47 +263,26 @@ groups:
222263
fern generate --group python-sdk --version ${{ inputs.version }} --log-level debug
223264
```
224265

225-
</Step>
266+
</Step>
226267

227-
<Step title="Run your workflow">
268+
<Step title="Regenerate and release your SDK">
228269

229-
Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**.
230-
231-
This regenerates your SDK, tags the new release with the version number you specified, and initiates a Fern-generated publishing workflow in your Python SDK repository that publishes your release to PyPi.
270+
Navigate to the **Actions** tab, select the workflow you just created, specify a version number, and click **Run workflow**. This regenerates your SDK.
232271

233272
<Frame>
234273
<img src="assets/python-sdk-release-action.png" alt="Running Python publish workflow" />
235274
</Frame>
236275
237-
Once your workflow completes, log back into PyPi and navigate to **Packages** to see your new release.
276+
<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
277+
278+
Once the workflow completes, you can view your new release by logging into PyPi and navigating to **Your projects**.
238279
239280
</Step>
240281
</Steps>
241282

242283
</Accordion>
243284
<Accordion title="Release via CLI and environment variables">
244285
<Steps>
245-
246-
<Step title="Configure PyPI authentication token">
247-
248-
Add `token: ${PYPI_TOKEN}` to `generators.yml` to tell Fern to use the `PYPI_TOKEN` environment variable for authentication when publishing to the PyPI registry.
249-
250-
```yaml title="Python" {9}
251-
groups:
252-
python-sdk:
253-
generators:
254-
- name: fernapi/fern-python-sdk
255-
version: <Markdown src="/snippets/version-number-python.mdx"/>
256-
output:
257-
location: pypi
258-
package-name: your-package-name
259-
token: ${PYPI_TOKEN}
260-
config:
261-
client_class_name: YourClientName
262-
github:
263-
repository: your-org/company-python
264-
```
265-
</Step>
266286

267287
<Step title="Set PyPI environment variable">
268288

@@ -274,16 +294,16 @@ groups:
274294

275295
</Step>
276296

277-
<Step title="Generate your release">
297+
<Step title="Regenerate and release your SDK">
278298

279-
Regenerate your SDK and publish it on PyPI:
299+
Regenerate your SDK, specifying the version:
280300

281301
```bash
282302
fern generate --group python-sdk --version <version>
283303
```
284-
Local machine output will verify that the release is pushed to your
285-
repository and tagged with the version you specified. Log back into PyPI and
286-
navigate to **Your projects** to see your new release.
304+
<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
305+
306+
Once the workflow completes, you can view your new release by logging into PyPi and navigating to **Your projects**.
287307
</Step>
288308

289309
</Steps>

‎fern/products/sdks/overview/typescript/publishing-to-npm.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -186,11 +186,7 @@ groups:
186186
</Step>
187187
<Step title="Choose your publishing mode">
188188

189-
Optionally set the mode to control how Fern handles SDK publishing:
190-
191-
- `mode: release` (default): Fern generates code, commits to main, and tags a release automatically
192-
- `mode: pull-request`: Fern generates code and creates a PR for you to review before release
193-
- `mode: push`: Fern generates code and pushes to a branch you specify for you to review before release
189+
<Markdown src="/products/sdks/snippets/github-publishing-mode.mdx"/>
194190

195191
```yaml title="generators.yml" {14}
196192
groups:
@@ -209,7 +205,6 @@ groups:
209205
mode: push
210206
branch: your-branch-name # Required for mode: push
211207
```
212-
You can also configure other settings, like the reviewers or license. Refer to the [full `github` (`generators.yml`) reference](/sdks/reference/generators-yml#github) for more information.
213208

214209
</Step>
215210
</Steps>
@@ -304,6 +299,8 @@ Set up a release workflow via [GitHub Actions](https://docs.github.com/en/action
304299
</Frame>
305300

306301
<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
302+
303+
Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**.
307304

308305
</Step>
309306

@@ -332,6 +329,9 @@ fern generate --group ts-sdk --version <version>
332329
```
333330

334331
<Markdown src="/products/sdks/snippets/release-sdk.mdx"/>
332+
333+
Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**.
334+
335335
</Step>
336336

337337
</Steps>

‎fern/products/sdks/snippets/github-publishing-mode.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Optionally set the mode to control how Fern handles SDK publishing:
2+
3+
- `mode: release` (default): Fern generates code, commits to main, and tags a release automatically
4+
- `mode: pull-request`: Fern generates code and creates a PR for you to review before release
5+
- `mode: push`: Fern generates code and pushes to a branch you specify for you to review before release
6+
7+
You can also configure other settings, like the reviewers or license. Refer to the [full `github` (`generators.yml`) reference](/sdks/reference/generators-yml#github) for more information.

‎fern/products/sdks/snippets/release-sdk.mdx‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,4 @@ The rest of the release process depends on your chosen mode:
22

33
- **Release mode (default):** If you didn't specify a `mode` or set `mode: release`, no further action is required. Fern automatically tags the new release with your specified version number and initiates the npm publishing workflow in your SDK repository.
44

5-
- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (`pull-request`) or branch (`push`), then [tag a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to initiate the npm publishing workflow in your SDK repository.
6-
7-
Once the workflow completes, you can view your new release by logging into npm and navigating to **Packages**.
5+
- **Pull request or push mode:** If you set `mode: pull-request` or `mode: push`, Fern creates a pull request or pushes to a branch respectively. Review and merge the PR (`pull-request`) or branch (`push`), then [tag a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) to initiate the npm publishing workflow in your SDK repository.

0 commit comments

Comments
 (0)