Skip to content

Commit e6be705

Browse files
authored
docs: mark docs upload as an alpha (#1214)
1 parent 3211e23 commit e6be705

File tree

4 files changed

+84
-87
lines changed

4 files changed

+84
-87
lines changed

README.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,6 @@ npm run build && npm run build:docs
171171

172172
* [`rdme autocomplete`](documentation/commands/autocomplete.md) - Display autocomplete installation instructions.
173173
* [`rdme changelogs`](documentation/commands/changelogs.md) - Upload Markdown files to your ReadMe project as Changelog posts.
174-
* [`rdme docs`](documentation/commands/docs.md) - Upload Markdown files to the Guides section of your ReadMe project.
175174
* [`rdme help`](documentation/commands/help.md) - Display help for rdme.
176175
* [`rdme login`](documentation/commands/login.md) - Login to a ReadMe project.
177176
* [`rdme logout`](documentation/commands/logout.md) - Logs the currently authenticated user out of ReadMe.

__tests__/commands/docs/__snapshots__/upload.test.ts.snap

Lines changed: 78 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
exports[`rdme docs upload > given that ReadMe project has bidirection sync set up > should error if validation is not skipped 1`] = `
44
{
55
"error": [Error: Bi-directional syncing is enabled for this project. Uploading these docs will overwrite what's currently synced from Git. To proceed with the upload, re-run this command with the \`--skip-validation\` flag.],
6-
"stderr": "",
6+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
7+
Use at your own risk!
8+
",
79
"stdout": "",
810
}
911
`;
@@ -13,7 +15,9 @@ exports[`rdme docs upload > given that ReadMe project has bidirection sync set u
1315
"error": [APIv2Error: ReadMe API error: The API key couldn't be located.
1416
1517
The API key you passed in (bad-api-key) doesn't match any keys we have in our system. API keys must be passed in via Bearer token. You can get your API key in Configuration > API Key, or in the docs.],
16-
"stderr": "",
18+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
19+
Use at your own risk!
20+
",
1721
"stdout": "",
1822
}
1923
`;
@@ -33,7 +37,9 @@ exports[`rdme docs upload > given that ReadMe project has bidirection sync set u
3337
"skipped": [],
3438
"updated": [],
3539
},
36-
"stderr": " › Warning: Bi-directional syncing is enabled for this project. Uploading
40+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
41+
Use at your own risk!
42+
Warning: Bi-directional syncing is enabled for this project. Uploading
3743
these docs will overwrite what's currently synced from Git.
3844
- 🚀 Uploading files to ReadMe...
3945
✔ 🚀 Uploading files to ReadMe... done!
@@ -77,7 +83,9 @@ exports[`rdme docs upload > given that the file path is a directory > given that
7783
"skipped": [],
7884
"updated": [],
7985
},
80-
"stderr": "- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/multiple-docs...
86+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
87+
Use at your own risk!
88+
- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/multiple-docs...
8189
✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/multiple-docs... 4 file(s) found!
8290
- 🔬 Validating frontmatter data...
8391
✔ 🔬 Validating frontmatter data... no issues found!
@@ -114,7 +122,9 @@ exports[`rdme docs upload > given that the file path is a directory > should cre
114122
"skipped": [],
115123
"updated": [],
116124
},
117-
"stderr": "- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs...
125+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
126+
Use at your own risk!
127+
- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs...
118128
✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs... 2 file(s) found!
119129
- 🔬 Validating frontmatter data...
120130
✔ 🔬 Validating frontmatter data... no issues found!
@@ -131,7 +141,9 @@ exports[`rdme docs upload > given that the file path is a directory > should cre
131141
exports[`rdme docs upload > given that the file path is a directory > should error out if the directory does not contain any Markdown files 1`] = `
132142
{
133143
"error": [Error: The directory you provided (__tests__/__fixtures__/ref-oas) doesn't contain any of the following file extensions: .markdown, .md, .mdx.],
134-
"stderr": "- 🔍 Looking for Markdown files in __tests__/__fixtures__/ref-oas...
144+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
145+
Use at your own risk!
146+
- 🔍 Looking for Markdown files in __tests__/__fixtures__/ref-oas...
135147
✖ 🔍 Looking for Markdown files in __tests__/__fixtures__/ref-oas... no files found.
136148
",
137149
"stdout": "",
@@ -141,7 +153,9 @@ exports[`rdme docs upload > given that the file path is a directory > should err
141153
exports[`rdme docs upload > given that the file path is a directory > should handle a mix of creates and updates and failures and skipped files (dry run) 1`] = `
142154
{
143155
"error": [AggregateError: Multiple dry runs failed. To see more detailed errors for a page, run \`rdme docs upload <path-to-page.md>\` --dry-run.],
144-
"stderr": "- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs...
156+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
157+
› Use at your own risk!
158+
- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs...
145159
✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs... 5 file(s) found!
146160
- 🔬 Validating frontmatter data...
147161
⚠ 🔬 Validating frontmatter data... issues found in 2 file(s).
@@ -167,7 +181,9 @@ exports[`rdme docs upload > given that the file path is a directory > should han
167181
exports[`rdme docs upload > given that the file path is a directory > should handle a mix of creates and updates and failures and skipped files 1`] = `
168182
{
169183
"error": [AggregateError: Multiple page uploads failed. To see more detailed errors for a page, run \`rdme docs upload <path-to-page.md>\`.],
170-
"stderr": "- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs...
184+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
185+
› Use at your own risk!
186+
- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs...
171187
✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/mixed-docs... 5 file(s) found!
172188
- 🔬 Validating frontmatter data...
173189
⚠ 🔬 Validating frontmatter data... issues found in 2 file(s).
@@ -211,7 +227,9 @@ exports[`rdme docs upload > given that the file path is a directory > should upd
211227
},
212228
],
213229
},
214-
"stderr": "- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs...
230+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
231+
Use at your own risk!
232+
- 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs...
215233
✔ 🔍 Looking for Markdown files in __tests__/__fixtures__/docs/existing-docs... 2 file(s) found!
216234
- 🔬 Validating frontmatter data...
217235
✔ 🔬 Validating frontmatter data... no issues found!
@@ -240,7 +258,9 @@ exports[`rdme docs upload > given that the file path is a single file > and the
240258
"skipped": [],
241259
"updated": [],
242260
},
243-
"stderr": "- 🔬 Validating frontmatter data...
261+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
262+
Use at your own risk!
263+
- 🔬 Validating frontmatter data...
244264
✔ 🔬 Validating frontmatter data... no issues found!
245265
- 🚀 Uploading files to ReadMe...
246266
✔ 🚀 Uploading files to ReadMe... done!
@@ -254,7 +274,9 @@ exports[`rdme docs upload > given that the file path is a single file > and the
254274
exports[`rdme docs upload > given that the file path is a single file > and the command is being run in a CI environment > should error out if the file has validation errors 1`] = `
255275
{
256276
"error": [Error: 1 file(s) have issues that should be fixed before uploading to ReadMe. Please run \`rdme docs upload __tests__/__fixtures__/docs/mixed-docs/legacy-category.md --dry-run\` in a non-CI environment to fix them.],
257-
"stderr": "- 🔬 Validating frontmatter data...
277+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
278+
› Use at your own risk!
279+
- 🔬 Validating frontmatter data...
258280
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
259281
",
260282
"stdout": "",
@@ -264,7 +286,9 @@ exports[`rdme docs upload > given that the file path is a single file > and the
264286
exports[`rdme docs upload > given that the file path is a single file > given that the --dry-run flag is passed > should error out if a non-404 error is returned from the HEAD request 1`] = `
265287
{
266288
"error": [APIv2Error: The ReadMe API responded with an unexpected error. Please try again and if this issue persists, get in touch with us at support@readme.io.],
267-
"stderr": "- 🔬 Validating frontmatter data...
289+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
290+
Use at your own risk!
291+
- 🔬 Validating frontmatter data...
268292
✔ 🔬 Validating frontmatter data... no issues found!
269293
- 🎭 Uploading files to ReadMe (but not really because it's a dry run)...
270294
✖ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... 1 file(s) failed.
@@ -290,7 +314,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
290314
"skipped": [],
291315
"updated": [],
292316
},
293-
"stderr": "- 🔬 Validating frontmatter data...
317+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
318+
Use at your own risk!
319+
- 🔬 Validating frontmatter data...
294320
✔ 🔬 Validating frontmatter data... no issues found!
295321
- 🎭 Uploading files to ReadMe (but not really because it's a dry run)...
296322
✔ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... done!
@@ -316,7 +342,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
316342
},
317343
],
318344
},
319-
"stderr": "- 🔬 Validating frontmatter data...
345+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
346+
Use at your own risk!
347+
- 🔬 Validating frontmatter data...
320348
✔ 🔬 Validating frontmatter data... no issues found!
321349
- 🎭 Uploading files to ReadMe (but not really because it's a dry run)...
322350
✔ 🎭 Uploading files to ReadMe (but not really because it's a dry run)... done!
@@ -330,7 +358,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
330358
exports[`rdme docs upload > given that the file path is a single file > given that the file has frontmatter issues > should exit if the user declines to fix the issues 1`] = `
331359
{
332360
"error": [Error: Aborting upload due to user input.],
333-
"stderr": "- 🔬 Validating frontmatter data...
361+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
362+
Use at your own risk!
363+
- 🔬 Validating frontmatter data...
334364
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
335365
",
336366
"stdout": "",
@@ -352,7 +382,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
352382
"skipped": [],
353383
"updated": [],
354384
},
355-
"stderr": "- 🔬 Validating frontmatter data...
385+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
386+
Use at your own risk!
387+
- 🔬 Validating frontmatter data...
356388
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
357389
- 🚀 Uploading files to ReadMe...
358390
✔ 🚀 Uploading files to ReadMe... done!
@@ -378,7 +410,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
378410
"skipped": [],
379411
"updated": [],
380412
},
381-
"stderr": "- 🔬 Validating frontmatter data...
413+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
414+
Use at your own risk!
415+
- 🔬 Validating frontmatter data...
382416
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
383417
- 🚀 Uploading files to ReadMe...
384418
✔ 🚀 Uploading files to ReadMe... done!
@@ -394,7 +428,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
394428
"error": [APIv2Error: ReadMe API error: bad request
395429
396430
your category is whack],
397-
"stderr": " › Warning: Skipping pre-upload validation of the Markdown file(s). This is
431+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
432+
Use at your own risk!
433+
Warning: Skipping pre-upload validation of the Markdown file(s). This is
398434
not recommended.
399435
- 🚀 Uploading files to ReadMe...
400436
✖ 🚀 Uploading files to ReadMe... 1 file(s) failed.
@@ -420,7 +456,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
420456
"skipped": [],
421457
"updated": [],
422458
},
423-
"stderr": "- 🔬 Validating frontmatter data...
459+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
460+
Use at your own risk!
461+
- 🔬 Validating frontmatter data...
424462
⚠ 🔬 Validating frontmatter data... issues found in 1 file(s).
425463
Warning: 1 file(s) have issues that cannot be fixed automatically. The
426464
upload will proceed but we recommend addressing these issues. Please get
@@ -449,7 +487,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
449487
"skipped": [],
450488
"updated": [],
451489
},
452-
"stderr": "- 🔬 Validating frontmatter data...
490+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
491+
Use at your own risk!
492+
- 🔬 Validating frontmatter data...
453493
✔ 🔬 Validating frontmatter data... no issues found!
454494
- 🚀 Uploading files to ReadMe...
455495
✔ 🚀 Uploading files to ReadMe... done!
@@ -475,7 +515,9 @@ exports[`rdme docs upload > given that the file path is a single file > given th
475515
},
476516
],
477517
},
478-
"stderr": "- 🔬 Validating frontmatter data...
518+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
519+
Use at your own risk!
520+
- 🔬 Validating frontmatter data...
479521
✔ 🔬 Validating frontmatter data... no issues found!
480522
- 🚀 Uploading files to ReadMe...
481523
✔ 🚀 Uploading files to ReadMe... done!
@@ -501,7 +543,9 @@ exports[`rdme docs upload > given that the file path is a single file > should a
501543
"skipped": [],
502544
"updated": [],
503545
},
504-
"stderr": "- 🔬 Validating frontmatter data...
546+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
547+
Use at your own risk!
548+
- 🔬 Validating frontmatter data...
505549
✔ 🔬 Validating frontmatter data... no issues found!
506550
- 🚀 Uploading files to ReadMe...
507551
✔ 🚀 Uploading files to ReadMe... done!
@@ -527,7 +571,9 @@ exports[`rdme docs upload > given that the file path is a single file > should c
527571
"skipped": [],
528572
"updated": [],
529573
},
530-
"stderr": "- 🔬 Validating frontmatter data...
574+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
575+
Use at your own risk!
576+
- 🔬 Validating frontmatter data...
531577
✔ 🔬 Validating frontmatter data... no issues found!
532578
- 🚀 Uploading files to ReadMe...
533579
✔ 🚀 Uploading files to ReadMe... done!
@@ -541,7 +587,9 @@ exports[`rdme docs upload > given that the file path is a single file > should c
541587
exports[`rdme docs upload > given that the file path is a single file > should error out if a non-404 error is returned from the HEAD request 1`] = `
542588
{
543589
"error": [APIv2Error: The ReadMe API responded with an unexpected error. Please try again and if this issue persists, get in touch with us at support@readme.io.],
544-
"stderr": "- 🔬 Validating frontmatter data...
590+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
591+
Use at your own risk!
592+
- 🔬 Validating frontmatter data...
545593
✔ 🔬 Validating frontmatter data... no issues found!
546594
- 🚀 Uploading files to ReadMe...
547595
✖ 🚀 Uploading files to ReadMe... 1 file(s) failed.
@@ -555,15 +603,19 @@ exports[`rdme docs upload > given that the file path is a single file > should e
555603
exports[`rdme docs upload > given that the file path is a single file > should error out if the file does not exist 1`] = `
556604
{
557605
"error": [Error: Oops! We couldn't locate a file or directory at the path you provided.],
558-
"stderr": "",
606+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
607+
Use at your own risk!
608+
",
559609
"stdout": "",
560610
}
561611
`;
562612
563613
exports[`rdme docs upload > given that the file path is a single file > should error out if the file has an invalid file extension 1`] = `
564614
{
565615
"error": [Error: Invalid file extension (.json). Must be one of the following: .markdown, .md, .mdx],
566-
"stderr": "",
616+
"stderr": " › Warning: This command is in an experimental alpha and is likely to change.
617+
Use at your own risk!
618+
",
567619
"stdout": "",
568620
}
569621
`;

documentation/commands/docs.md

Lines changed: 0 additions & 59 deletions
This file was deleted.

src/commands/docs/upload.ts

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,16 @@ import BaseCommand from '../../lib/baseCommand.js';
44
import { githubFlag, keyFlag } from '../../lib/flags.js';
55
import syncPagePath from '../../lib/syncPagePath.js';
66

7+
const alphaNotice = 'This command is in an experimental alpha and is likely to change. Use at your own risk!';
8+
79
export default class DocsUploadCommand extends BaseCommand<typeof DocsUploadCommand> {
810
id = 'docs upload' as const;
911

1012
route = 'guides' as const;
1113

12-
static summary = 'Upload Markdown files to the Guides section of your ReadMe project.';
14+
static hidden = true;
15+
16+
static summary = `Upload Markdown files to the Guides section of your ReadMe project.\n\nNOTE: ${alphaNotice}`;
1317

1418
static description =
1519
'The path can either be a directory or a single Markdown file. The Markdown files will require YAML frontmatter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your frontmatter: https://docs.readme.com/main/docs/rdme#markdown-file-setup';
@@ -60,6 +64,7 @@ export default class DocsUploadCommand extends BaseCommand<typeof DocsUploadComm
6064
};
6165

6266
async run() {
67+
this.warn(alphaNotice);
6368
return syncPagePath.call(this);
6469
}
6570
}

0 commit comments

Comments
 (0)