Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs): consolidate single commands #642

Merged
merged 17 commits into from
Oct 27, 2022
Merged

feat(docs): consolidate single commands #642

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
6f900c7
chore: remove JSDoc types
kanadgupta Oct 24, 2022
86af248
refactor(changelogs): remove single command
kanadgupta Oct 24, 2022
65f43a4
chore: clean up comment
kanadgupta Oct 24, 2022
85b47d9
test(changelogs): fix tests
kanadgupta Oct 26, 2022
6d31891
refactor: file/func name, param order
kanadgupta Oct 26, 2022
36ee046
refactor: another small thing
kanadgupta Oct 26, 2022
66c4112
fix: whoops
kanadgupta Oct 26, 2022
49b668d
test(changelogs): small cleanup
kanadgupta Oct 26, 2022
0b37740
feat: consolidate custompage commands
kanadgupta Oct 26, 2022
99fa1d1
docs(changelog/custompages): updates
kanadgupta Oct 26, 2022
cd7daf4
chore: rename files
kanadgupta Oct 27, 2022
df32464
Merge branch 'main' into kanad/rm-5580-consolidate-docs-and-docssingle
kanadgupta Oct 27, 2022
a5e2952
test: small naming convention fix
kanadgupta Oct 27, 2022
b282a71
feat: consolidate docs commands
kanadgupta Oct 27, 2022
da9fcf1
refactor: consolidate function
kanadgupta Oct 27, 2022
73c763b
chore: whooops
kanadgupta Oct 27, 2022
e0e99dd
docs: cleanup
kanadgupta Oct 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 7 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,14 +195,12 @@ The command will ask you a couple questions about how you wish to reduce the fil

### Docs

#### Syncing a Folder of Markdown Docs to ReadMe

The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.

Passing in a path to a directory will also sync any Markdown files that are located in subdirectories.
Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path input can also be individual Markdown files.

```sh
rdme docs path-to-markdown-files --version={project-version}
rdme docs [path] --version={project-version}
```

This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).
Expand All @@ -212,61 +210,33 @@ This command also has a dry run mode, which can be useful for initial setup and
If you wish to delete documents from ReadMe that are no longer present in your local directory:

```sh
rdme docs:prune path-to-markdown-files
```

#### Edit a Single ReadMe Doc on Your Local Machine

```sh
rdme docs:edit <slug> --version={project-version}
```

#### Syncing a Single Markdown File to ReadMe

```sh
rdme docs:single path-to-markdown-file --version={project-version}
rdme docs:prune path-to-directory-of-markdown
```

### Changelogs

#### Syncing a Folder of Markdown to ReadMe

The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.

Passing in a path to a directory will also sync any Markdown files that are located in subdirectories.
Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path input can also be individual Markdown files.

```sh
rdme changelogs path-to-markdown-files
rdme changelogs [path]
```

This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).

#### Syncing a Single Markdown File to ReadMe

```sh
rdme changelogs:single path-to-markdown-file
```

### Custom Pages

#### Syncing a Folder of Custom Pages to ReadMe

Custom Pages has support for both Markdown and HTML files. These files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info on setting up your front matter.

Passing in a path to a directory will also sync any HTML/Markdown files that are located in subdirectories.
Passing in a path to a directory will also sync any HTML/Markdown files that are located in subdirectories. The path input can also be individual HTML/Markdown files.

```sh
rdme custompages path-to-markdown-files
rdme custompages [path]
```

This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode).

#### Syncing a Single Custom Page to ReadMe

```sh
rdme custompages:single path-to-markdown-file
```

### Versions

#### Get All Versions Associated With Your Project
Expand Down
32 changes: 17 additions & 15 deletions __tests__/cmds/changelogs/index.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,21 +37,23 @@ describe('rdme changelogs', () => {
delete process.env.TEST_CI;
});

it('should error if no folder provided', () => {
return expect(changelogs.run({ key })).rejects.toThrow(
'No folder provided. Usage `rdme changelogs <folder> [options]`.'
it('should error if no path provided', () => {
return expect(changelogs.run({ key })).rejects.toStrictEqual(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not do .toThrow here anymore?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.toThrow is technically a partial match on err.message, .toStrictEqual(<full error object>) is a stricter check

new Error('No path provided. Usage `rdme changelogs <path> [options]`.')
);
});

it('should error if the argument is not a folder', () => {
return expect(changelogs.run({ key, folder: 'not-a-folder' })).rejects.toThrow(
"ENOENT: no such file or directory, scandir 'not-a-folder'"
return expect(changelogs.run({ key, filePath: 'not-a-folder' })).rejects.toStrictEqual(
new Error("Oops! We couldn't locate a file or directory at the path you provided.")
);
});

it('should error if the folder contains no markdown files', () => {
return expect(changelogs.run({ key, folder: '.github/workflows' })).rejects.toThrow(
'We were unable to locate Markdown files in .github/workflows.'
return expect(changelogs.run({ key, filePath: '.github/workflows' })).rejects.toStrictEqual(
new Error(
"The directory you provided (.github/workflows) doesn't contain any of the following required files: .markdown, .md."
)
);
});

Expand Down Expand Up @@ -107,7 +109,7 @@ describe('rdme changelogs', () => {
.basicAuth({ user: key })
.reply(200, { slug: anotherDoc.slug, body: anotherDoc.doc.content });

return changelogs.run({ folder: `./__tests__/${fixturesBaseDir}/existing-docs`, key }).then(updatedDocs => {
return changelogs.run({ filePath: `./__tests__/${fixturesBaseDir}/existing-docs`, key }).then(updatedDocs => {
// All changelogs should have been updated because their hashes from the GET request were different from what they
// are currently.
expect(updatedDocs).toBe(
Expand All @@ -134,7 +136,7 @@ describe('rdme changelogs', () => {
.reply(200, { slug: anotherDoc.slug, lastUpdatedHash: 'anOldHash' });

return changelogs
.run({ dryRun: true, folder: `./__tests__/${fixturesBaseDir}/existing-docs`, key })
.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/existing-docs`, key })
.then(updatedDocs => {
// All changelogs should have been updated because their hashes from the GET request were different from what they
// are currently.
Expand Down Expand Up @@ -164,7 +166,7 @@ describe('rdme changelogs', () => {
.basicAuth({ user: key })
.reply(200, { slug: anotherDoc.slug, lastUpdatedHash: anotherDoc.hash });

return changelogs.run({ folder: `./__tests__/${fixturesBaseDir}/existing-docs`, key }).then(skippedDocs => {
return changelogs.run({ filePath: `./__tests__/${fixturesBaseDir}/existing-docs`, key }).then(skippedDocs => {
expect(skippedDocs).toBe(
[
'`simple-doc` was not updated because there were no changes.',
Expand All @@ -188,7 +190,7 @@ describe('rdme changelogs', () => {
.reply(200, { slug: anotherDoc.slug, lastUpdatedHash: anotherDoc.hash });

return changelogs
.run({ dryRun: true, folder: `./__tests__/${fixturesBaseDir}/existing-docs`, key })
.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/existing-docs`, key })
.then(skippedDocs => {
expect(skippedDocs).toBe(
[
Expand Down Expand Up @@ -224,7 +226,7 @@ describe('rdme changelogs', () => {
.basicAuth({ user: key })
.reply(201, { slug, _id: id, body: doc.content, ...doc.data, lastUpdatedHash: hash });

await expect(changelogs.run({ folder: `./__tests__/${fixturesBaseDir}/new-docs`, key })).resolves.toBe(
await expect(changelogs.run({ filePath: `./__tests__/${fixturesBaseDir}/new-docs`, key })).resolves.toBe(
`🌱 successfully created 'new-doc' (ID: 1234) with contents from __tests__/${fixturesBaseDir}/new-docs/new-doc.md`
);

Expand All @@ -247,7 +249,7 @@ describe('rdme changelogs', () => {
});

await expect(
changelogs.run({ dryRun: true, folder: `./__tests__/${fixturesBaseDir}/new-docs`, key })
changelogs.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/new-docs`, key })
).resolves.toBe(
`🎭 dry run! This will create 'new-doc' with contents from __tests__/${fixturesBaseDir}/new-docs/new-doc.md with the following metadata: ${JSON.stringify(
doc.data
Expand Down Expand Up @@ -313,7 +315,7 @@ describe('rdme changelogs', () => {
message: `Error uploading ${chalk.underline(`${fullDirectory}/${slug}.md`)}:\n\n${errorObject.message}`,
};

await expect(changelogs.run({ folder: `./${fullDirectory}`, key })).rejects.toStrictEqual(
await expect(changelogs.run({ filePath: `./${fullDirectory}`, key })).rejects.toStrictEqual(
new APIError(formattedErrorObject)
);

Expand Down Expand Up @@ -344,7 +346,7 @@ describe('rdme changelogs', () => {
.basicAuth({ user: key })
.reply(201, { slug: doc.data.slug, _id: id, body: doc.content, ...doc.data, lastUpdatedHash: hash });

await expect(changelogs.run({ folder: `./__tests__/${fixturesBaseDir}/slug-docs`, key })).resolves.toBe(
await expect(changelogs.run({ filePath: `./__tests__/${fixturesBaseDir}/slug-docs`, key })).resolves.toBe(
`🌱 successfully created 'marc-actually-wrote-a-test' (ID: 1234) with contents from __tests__/${fixturesBaseDir}/slug-docs/new-doc-slug.md`
);

Expand Down
48 changes: 22 additions & 26 deletions __tests__/cmds/changelogs/single.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,52 +6,52 @@ import frontMatter from 'gray-matter';
import nock from 'nock';
import prompts from 'prompts';

import SingleChangelogCommand from '../../../src/cmds/changelogs/single';
import ChangelogsCommand from '../../../src/cmds/changelogs';
import APIError from '../../../src/lib/apiError';
import getAPIMock from '../../helpers/get-api-mock';
import hashFileContents from '../../helpers/hash-file-contents';

const changelogsSingle = new SingleChangelogCommand();
const changelogs = new ChangelogsCommand();

const fixturesBaseDir = '__fixtures__/changelogs';
const fullFixturesDir = `${__dirname}./../../${fixturesBaseDir}`;
const key = 'API_KEY';

describe('rdme changelogs:single', () => {
describe('rdme changelogs (single)', () => {
beforeAll(() => nock.disableNetConnect());

afterAll(() => nock.cleanAll());

it('should prompt for login if no API key provided', async () => {
const consoleInfoSpy = jest.spyOn(console, 'info').mockImplementation();
prompts.inject(['this-is-not-an-email', 'password', 'subdomain']);
await expect(changelogsSingle.run({})).rejects.toStrictEqual(new Error('You must provide a valid email address.'));
await expect(changelogs.run({})).rejects.toStrictEqual(new Error('You must provide a valid email address.'));
consoleInfoSpy.mockRestore();
});

it('should error in CI if no API key provided', async () => {
process.env.TEST_CI = 'true';
await expect(changelogsSingle.run({})).rejects.toStrictEqual(
await expect(changelogs.run({})).rejects.toStrictEqual(
new Error('No project API key provided. Please use `--key`.')
);
delete process.env.TEST_CI;
});

it('should error if no file path provided', () => {
return expect(changelogsSingle.run({ key })).rejects.toThrow(
'No file path provided. Usage `rdme changelogs:single <file> [options]`.'
return expect(changelogs.run({ key })).rejects.toStrictEqual(
new Error('No path provided. Usage `rdme changelogs <path> [options]`.')
);
});

it('should error if the argument is not a Markdown file', async () => {
await expect(changelogsSingle.run({ key, filePath: 'not-a-markdown-file' })).rejects.toThrow(
'The file path specified is not a Markdown file.'
it('should error if the argument is not a Markdown file', () => {
return expect(changelogs.run({ key, filePath: 'package.json' })).rejects.toStrictEqual(
new Error('Invalid file extension (.json). Must be one of the following: .markdown, .md')
);
});

it('should support .markdown files but error if file path cannot be found', async () => {
await expect(changelogsSingle.run({ key, filePath: 'non-existent-file.markdown' })).rejects.toThrow(
'ENOENT: no such file or directory'
it('should support .markdown files but error if file path cannot be found', () => {
return expect(changelogs.run({ key, filePath: 'non-existent-file.markdown' })).rejects.toStrictEqual(
new Error("Oops! We couldn't locate a file or directory at the path you provided.")
);
});

Expand All @@ -78,7 +78,7 @@ describe('rdme changelogs:single', () => {
.reply(201, { slug, _id: id, body: doc.content, ...doc.data });

await expect(
changelogsSingle.run({ filePath: `./__tests__/${fixturesBaseDir}/new-docs/new-doc.md`, key })
changelogs.run({ filePath: `./__tests__/${fixturesBaseDir}/new-docs/new-doc.md`, key })
).resolves.toBe(
`🌱 successfully created 'new-doc' (ID: 1234) with contents from ./__tests__/${fixturesBaseDir}/new-docs/new-doc.md`
);
Expand All @@ -102,7 +102,7 @@ describe('rdme changelogs:single', () => {
});

await expect(
changelogsSingle.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/new-docs/new-doc.md`, key })
changelogs.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/new-docs/new-doc.md`, key })
).resolves.toBe(
`🎭 dry run! This will create 'new-doc' with contents from ./__tests__/${fixturesBaseDir}/new-docs/new-doc.md with the following metadata: ${JSON.stringify(
doc.data
Expand Down Expand Up @@ -150,9 +150,7 @@ describe('rdme changelogs:single', () => {
message: `Error uploading ${chalk.underline(`${filePath}`)}:\n\n${errorObject.message}`,
};

await expect(changelogsSingle.run({ filePath: `${filePath}`, key })).rejects.toStrictEqual(
new APIError(formattedErrorObject)
);
await expect(changelogs.run({ filePath, key })).rejects.toStrictEqual(new APIError(formattedErrorObject));

getMock.done();
postMock.done();
Expand All @@ -177,9 +175,7 @@ describe('rdme changelogs:single', () => {
message: `Error uploading ${chalk.underline(`${filePath}`)}:\n\n${errorObject.message}`,
};

await expect(changelogsSingle.run({ filePath: `${filePath}`, key })).rejects.toStrictEqual(
new APIError(formattedErrorObject)
);
await expect(changelogs.run({ filePath, key })).rejects.toStrictEqual(new APIError(formattedErrorObject));

getMock.done();
});
Expand Down Expand Up @@ -208,7 +204,7 @@ describe('rdme changelogs:single', () => {
.reply(201, { slug: doc.data.slug, _id: id, body: doc.content, ...doc.data, lastUpdatedHash: hash });

await expect(
changelogsSingle.run({ filePath: `./__tests__/${fixturesBaseDir}/slug-docs/new-doc-slug.md`, key })
changelogs.run({ filePath: `./__tests__/${fixturesBaseDir}/slug-docs/new-doc-slug.md`, key })
).resolves.toBe(
`🌱 successfully created 'marc-actually-wrote-a-test' (ID: 1234) with contents from ./__tests__/${fixturesBaseDir}/slug-docs/new-doc-slug.md`
);
Expand Down Expand Up @@ -249,7 +245,7 @@ describe('rdme changelogs:single', () => {
body: simpleDoc.doc.content,
});

return changelogsSingle
return changelogs
.run({ filePath: `./__tests__/${fixturesBaseDir}/existing-docs/simple-doc.md`, key })
.then(updatedDocs => {
expect(updatedDocs).toBe(
Expand All @@ -269,7 +265,7 @@ describe('rdme changelogs:single', () => {
.basicAuth({ user: key })
.reply(200, { slug: simpleDoc.slug, lastUpdatedHash: 'anOldHash' });

return changelogsSingle
return changelogs
.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/existing-docs/simple-doc.md`, key })
.then(updatedDocs => {
// All changelogs should have been updated because their hashes from the GET request were different from what they
Expand All @@ -294,7 +290,7 @@ describe('rdme changelogs:single', () => {
.basicAuth({ user: key })
.reply(200, { slug: simpleDoc.slug, lastUpdatedHash: simpleDoc.hash });

return changelogsSingle
return changelogs
.run({ filePath: `./__tests__/${fixturesBaseDir}/existing-docs/simple-doc.md`, key })
.then(skippedDocs => {
expect(skippedDocs).toBe('`simple-doc` was not updated because there were no changes.');
Expand All @@ -309,7 +305,7 @@ describe('rdme changelogs:single', () => {
.basicAuth({ user: key })
.reply(200, { slug: simpleDoc.slug, lastUpdatedHash: simpleDoc.hash });

return changelogsSingle
return changelogs
.run({ dryRun: true, filePath: `./__tests__/${fixturesBaseDir}/existing-docs/simple-doc.md`, key })
.then(skippedDocs => {
expect(skippedDocs).toBe('🎭 dry run! `simple-doc` will not be updated because there were no changes.');
Expand Down
Loading