Skip to content

Commit 94d234c

Browse files
yanthomasdevyanthomasdev
authored
Merge branch 'main' into i18n/fr-update-integrations-reference.mdx
2 parents d46d875 + c577ee7 commit 94d234c

28 files changed

Lines changed: 257 additions & 169 deletions

‎.github/workflows/nightly.yml‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,52 +10,92 @@ jobs:
1010
name: Generate Reference Docs
1111
if: github.repository_owner == 'withastro'
1212
runs-on: ubuntu-latest
13+
strategy:
14+
matrix:
15+
include:
16+
# Default options for running with latest Astro code
17+
- SOURCE_BRANCH: main
18+
TARGET_BRANCH: main
19+
LABEL: ci
20+
PR_BRANCH: ci/docgen
21+
PR_TITLE: 'ci: update reference docs'
22+
# Custom options for running with Astro v5 beta code
23+
- SOURCE_BRANCH: next
24+
TARGET_BRANCH: 5.0.0-beta
25+
LABEL: 5.0.0-beta,ci
26+
PR_BRANCH: ci/docgen-beta
27+
PR_TITLE: '[BETA] ci: update reference docs'
1328
steps:
1429
- name: Check out code using Git
1530
uses: actions/checkout@v4
31+
with:
32+
ref: ${{ matrix.TARGET_BRANCH }}
1633

1734
- name: Install Tools & Dependencies
1835
uses: ./.github/actions/install
1936

2037
- name: Run docgen script
2138
run: pnpm run docgen
39+
env:
40+
SOURCE_BRANCH: ${{ matrix.SOURCE_BRANCH }}
2241

2342
- name: Create Pull Request
2443
id: createpr
2544
uses: peter-evans/create-pull-request@v3
2645
with:
27-
branch: ci/docgen
46+
branch: ${{ matrix.PR_BRANCH }}
2847
token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
2948
add-paths: src/content/docs/en/reference/*.mdx
3049
commit-message: 'ci: update reference docs'
31-
title: 'ci: update reference docs'
50+
title: ${{ matrix.PR_TITLE }}
3251
body: |
3352
This PR is auto-generated by a nightly GitHub action to update the reference docs from source code in withastro/astro.
34-
labels: ci
53+
labels: ${{ matrix.LABEL }}
54+
base: ${{ matrix.TARGET_BRANCH }}
3555

3656
error:
3757
name: Generate Error Reference Docs
3858
if: github.repository_owner == 'withastro'
3959
runs-on: ubuntu-latest
60+
strategy:
61+
matrix:
62+
include:
63+
# Default options for running with latest Astro code
64+
- SOURCE_BRANCH: main
65+
TARGET_BRANCH: main
66+
LABEL: ci
67+
PR_BRANCH: ci/docgen-errors
68+
PR_TITLE: 'ci: update error reference docs'
69+
# Custom options for running with Astro v5 beta code
70+
- SOURCE_BRANCH: next
71+
TARGET_BRANCH: 5.0.0-beta
72+
LABEL: 5.0.0-beta,ci
73+
PR_BRANCH: ci/docgen-errors-beta
74+
PR_TITLE: '[BETA] ci: update error reference docs'
4075
steps:
4176
- name: Check out code using Git
4277
uses: actions/checkout@v4
78+
with:
79+
ref: ${{ matrix.TARGET_BRANCH }}
4380

4481
- name: Install Tools & Dependencies
4582
uses: ./.github/actions/install
4683

4784
- name: Run docgen script
4885
run: pnpm run docgen:errors
86+
env:
87+
SOURCE_BRANCH: ${{ matrix.SOURCE_BRANCH }}
4988

5089
- name: Create Pull Request
5190
id: createpr
5291
uses: peter-evans/create-pull-request@v3
5392
with:
54-
branch: ci/docgen-errors
93+
branch: ${{ matrix.PR_BRANCH }}
5594
token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
5695
add-paths: src/content/docs/en/reference/*.mdx
5796
commit-message: 'ci: update error reference docs'
58-
title: 'ci: update error reference docs'
97+
title: ${{ matrix.PR_TITLE }}
5998
body: |
6099
This PR is auto-generated by a nightly GitHub action to update the error reference docs from source code in withastro/astro.
61-
labels: ci
100+
labels: ${{ matrix.LABEL }}
101+
base: ${{ matrix.TARGET_BRANCH }}

‎.vscode/settings.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,11 @@
33
"src/content/docs/en/reference/errors/*": true,
44
"src/content/docs/en/reference/configuration-reference.mdx": true,
55
"src/content/docs/en/reference/error-reference.mdx": true
6+
},
7+
"[javascript]": {
8+
"editor.defaultFormatter": "esbenp.prettier-vscode"
9+
},
10+
"[typescript]": {
11+
"editor.defaultFormatter": "esbenp.prettier-vscode"
612
}
713
}

‎scripts/error-docgen.mjs‎

Lines changed: 54 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
import fs from 'fs';
21
import jsdoc from 'jsdoc-api';
32
import fetch from 'node-fetch';
3+
import fs from 'node:fs';
44
import ts from 'typescript';
55

66
const sourceBranch = process.env.SOURCE_BRANCH || 'main';
@@ -29,20 +29,24 @@ import DontEditWarning from '~/components/DontEditWarning.astro'
2929
The following reference is a complete list of the errors you may encounter while using Astro. For additional assistance, including common pitfalls, please also see our [Troubleshooting Guide](/en/guides/troubleshooting/).
3030
`;
3131

32-
const FOOTER = ``;
32+
const FOOTER = '';
3333

3434
export async function run() {
3535
const astroErrorData = await getAstroErrorsData();
3636

3737
// TODO: Implement compiler errors
3838

39+
const alreadyDocumentedErrors = fs.readdirSync('src/content/docs/en/reference/errors');
40+
41+
const documentedErrors = [];
42+
3943
let astroResult = '';
4044
for (const comment of astroErrorData.jsdoc) {
4145
// Header
4246
if (comment.kind === 'heading') {
4347
astroResult += `\n## ${comment.name}\n\n`;
4448
if (comment.description) {
45-
astroResult += comment.description.trim() + '\n\n';
49+
astroResult += `${comment.description.trim()}\n\n`;
4650
}
4751
continue;
4852
}
@@ -61,7 +65,7 @@ export async function run() {
6165
const completeReferenceEntry = [
6266
// Errors can be deprecated, as such we add a little "deprecated" caution to errors that needs it
6367
getDeprecatedText(comment.deprecated),
64-
``,
68+
'',
6569
// Get the error message and print it in a blockquote
6670
getMessage(
6771
comment.name,
@@ -70,23 +74,23 @@ export async function run() {
7074
),
7175
// Show the error's description under a header
7276
comment.description && `## What went wrong?\n${comment.description.trim()}`,
73-
``,
77+
'',
7478
// List @see entries
7579
comment.see
7680
? `**See Also:**\n${comment.see.map((s) => `- ${s.replace('-', '')}`.trim()).join('\n')}`
7781
: undefined,
78-
`\n\n`,
82+
'\n\n',
7983
]
8084
.filter((l) => l !== undefined)
8185
.join('\n')
8286
// Replace absolute links with relative ones
8387
.replace(/https\\?:\/\/docs\.astro\.build\//g, '/');
8488

8589
const fileName = getKebabFilename(comment.name);
86-
fs.writeFileSync(
87-
`src/content/docs/en/reference/errors/${fileName}.mdx`,
88-
getErrorReferenceEntryHeader(errorTitle) + completeReferenceEntry
89-
);
90+
const filePath = `src/content/docs/en/reference/errors/${fileName}.mdx`;
91+
fs.writeFileSync(filePath, getErrorReferenceEntryHeader(errorTitle) + completeReferenceEntry);
92+
93+
documentedErrors.push(`${fileName}.mdx`);
9094

9195
// Build string for error reference list
9296
astroResult += [
@@ -96,6 +100,34 @@ export async function run() {
96100
.join('\n');
97101
}
98102

103+
// Add deprecation notice for errors that are no longer emitted
104+
const deprecatedErrors = alreadyDocumentedErrors.filter(
105+
(error) => !documentedErrors.includes(error)
106+
);
107+
108+
for (const error of deprecatedErrors) {
109+
const filePath = `src/content/docs/en/reference/errors/${error}`;
110+
const currentContent = fs.readFileSync(filePath, 'utf8');
111+
112+
// If the error got removed without a deprecation, add a deprecation notice
113+
if (!currentContent.includes(':::caution[Deprecated]')) {
114+
fs.writeFileSync(
115+
filePath,
116+
currentContent.replace(
117+
'<DontEditWarning />',
118+
[
119+
'<DontEditWarning />',
120+
'',
121+
getDeprecatedText(
122+
'This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance.'
123+
),
124+
].join('\n')
125+
),
126+
'utf8'
127+
);
128+
}
129+
}
130+
99131
fs.writeFileSync(
100132
'src/content/docs/en/reference/error-reference.mdx',
101133
HEADER + astroResult + FOOTER,
@@ -124,7 +156,7 @@ export async function run() {
124156
}
125157

126158
if (resultMessage) {
127-
return resultMessage + '\n';
159+
return `${resultMessage}\n`;
128160
}
129161

130162
return undefined;
@@ -139,7 +171,7 @@ export async function run() {
139171
}
140172

141173
return [
142-
``,
174+
'',
143175
':::caution[Deprecated]',
144176
typeof deprecateMention === 'string'
145177
? deprecateMention
@@ -160,11 +192,15 @@ async function getAstroErrorsData() {
160192
const inputBuffer = STUB || (await fetch(errorURL).then((r) => r.text()));
161193

162194
const compiledResult = ts.transpileModule(inputBuffer, {
163-
compilerOptions: { module: 'esnext', target: 'esnext', removeComments: false },
195+
compilerOptions: {
196+
module: 'esnext',
197+
target: 'esnext',
198+
removeComments: false,
199+
},
164200
}).outputText;
165201

166202
const encodedJs = encodeURIComponent(compiledResult);
167-
const dataUri = 'data:text/javascript;charset=utf-8,' + encodedJs;
203+
const dataUri = `data:text/javascript;charset=utf-8,${encodedJs}`;
168204

169205
/**
170206
* @type {{AstroErrorData: Object.<string, {code: number, message: string, hint: string, name: string}>}
@@ -176,7 +212,7 @@ async function getAstroErrorsData() {
176212
*/
177213
const jsDocComments = jsdoc
178214
.explainSync({ source: compiledResult })
179-
.filter((data) => data.tags && data.tags.some((tag) => tag.title === 'docs'));
215+
.filter((data) => data.tags?.some((tag) => tag.title === 'docs'));
180216

181217
return {
182218
errors: data,
@@ -190,15 +226,15 @@ async function getAstroErrorsData() {
190226
* @returns {string}
191227
*/
192228
function getErrorReferenceEntryHeader(errorTitle) {
193-
errorTitle = errorTitle.replaceAll('`', '');
229+
const sanitizedTitle = errorTitle.replaceAll('`', '');
194230
return `
195231
---
196232
# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs'
197233
# Do not make edits to it directly, they will be overwritten.
198234
# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
199235
# Translators, please remove this note and the <DontEditWarning/> component.
200236
201-
title: ${errorTitle}
237+
title: ${sanitizedTitle}
202238
i18nReady: true
203239
githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
204240
---
@@ -241,7 +277,7 @@ function sanitizeString(message) {
241277
return message
242278
.replaceAll(/\\`/gm, '`')
243279
.replaceAll(/`?(client:[\w]+(="\(.+\)")?)`?/g, '`$1`')
244-
.replaceAll(/([^`\\])</gm, `$1\\<`)
280+
.replaceAll(/([^`\\])</gm, '$1\\<')
245281
.replaceAll(/>([^`\\])/gm, '\\$1>')
246282
.replaceAll('\\n', '<br/>');
247283
}

‎src/content/docs/en/guides/actions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import { Steps } from '@astrojs/starlight/components';
88
import Since from '~/components/Since.astro';
99
import ReadMore from '~/components/ReadMore.astro';
1010

11-
<p><Since v="4.14" /></p>
11+
<p><Since v="4.15" /></p>
1212

1313
Astro Actions allow you to define and call backend functions with type-safety. Actions perform data fetching, JSON parsing, and input validation for you. This can greatly reduce the amount of boilerplate needed compared to using an [API endpoint](/en/guides/endpoints/).
1414

‎src/content/docs/en/guides/astro-db.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -671,7 +671,7 @@ Details of the libSQL connection (e.g. encryption key, replication, sync interva
671671

672672
For example, to have a local file work as an embedded replica to an encrypted libSQL server, you can set the following environment variables:
673673

674-
```env title=".env"
674+
```dotenv title=".env"
675675
ASTRO_DB_REMOTE_URL=file://local-copy.db?encryptionKey=your-encryption-key&syncInterval=60&syncUrl=libsql%3A%2F%2Fyour.server.io
676676
ASTRO_DB_APP_TOKEN=token-to-your-remote-url
677677
```
@@ -690,7 +690,7 @@ libSQL supports both HTTP and WebSockets as the transport protocol for a remote
690690

691691
libSQL has native support for encrypted databases. Passing this search parameter will enable encryption using the given key:
692692

693-
```env title=".env"
693+
```dotenv title=".env"
694694
ASTRO_DB_REMOTE_URL=file:path/to/file.db?encryptionKey=your-encryption-key
695695
```
696696

@@ -702,7 +702,7 @@ Use this property to pass a separate connection URL to turn the DB into an embed
702702

703703
For example, to have an in-memory embedded replica of a database on `libsql://your.server.io`, you can set the connection URL as such:
704704

705-
```env title=".env"
705+
```dotenv title=".env"
706706
ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io
707707
```
708708

@@ -712,7 +712,7 @@ Interval between embedded replicas synchronizations in seconds. By default it on
712712

713713
This property is only used when `syncUrl` is also set. For example, to set an in-memory embedded replica to synchronize every minute set the following environment variable:
714714

715-
```env title=".env"
715+
```dotenv title=".env"
716716
ASTRO_DB_REMOTE_URL=memory:?syncUrl=libsql%3A%2F%2Fyour.server.io&syncInterval=60
717717
```
718718

‎src/content/docs/en/guides/view-transitions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -646,7 +646,7 @@ At this point of the lifecycle, you could choose to define your own swap impleme
646646

647647
<p><Since v="4.15.0" /></p>
648648

649-
The `swapFunction` object of the `astro:transitions/client` module provides five utility functions that handle specific swap-related tasks, including handling document attributes, page elements, and script execution. These functions can be used directly to define a custom swap implementation.
649+
The `swapFunctions` object of the `astro:transitions/client` module provides five utility functions that handle specific swap-related tasks, including handling document attributes, page elements, and script execution. These functions can be used directly to define a custom swap implementation.
650650

651651
The following example demonstrates how to use these functions to recreate Astro's built-in swap implementation:
652652

‎src/content/docs/en/reference/api-reference.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2137,13 +2137,13 @@ export const onRequest = defineMiddleware(async (context, next) => {
21372137
})
21382138
```
21392139

2140-
## Actions (astro:actions)
2140+
## Actions (`astro:actions`)
21412141

21422142
<p>
21432143
<Since v="4.15.0" />
21442144
</p>
21452145

2146-
Actions are backend functions used for type-safe server-to-client communication. All utilities to define and call actions are exposed by the `astro:actions` module. For examples and usage instructions, [see the Actions guide](/en/guides/actions/).
2146+
Actions help you build a type-safe backend you can call from client code and HTML forms. All utilities to define and call actions are exposed by the `astro:actions` module. For examples and usage instructions, [see the Actions guide](/en/guides/actions/).
21472147

21482148
### `defineAction()`
21492149

‎src/content/docs/en/reference/cli-reference.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -268,7 +268,7 @@ Generates TypeScript types for all Astro modules. This sets up a [`src/env.d.ts`
268268
- The `astro:content` module for the [Content Collections API](/en/guides/content-collections/).
269269
- The `astro:db` module for [Astro DB](/en/guides/astro-db/).
270270
- The `astro:env` module for [experimental Astro Env](/en/reference/configuration-reference/#experimentalenv).
271-
- The `astro:actions` module for [experimental Astro Actions](/en/reference/configuration-reference/#experimentalactions)
271+
- The `astro:actions` module for [Astro Actions](/en/guides/actions/)
272272

273273
## `astro add`
274274

0 commit comments

Comments
 (0)