chore Doc refactor with Admonitions #12498

Biki-das · 2022-02-25T15:43:04Z

this PR is gonna take time , in ref to #12495

made changes to first few docs as proof of concept

Biki-das · 2022-02-25T15:47:15Z

@SimenB this seems to be good change for the doc, i shall for now add :::note and other admonitions which seems appropriate to their places, later we can go through and do a final check .

weidehai · 2022-02-25T16:19:20Z

@SimenB this seems to be good change for the doc, i shall for now add :::note and other admonitions which seems appropriate to their places, later we can go through and do a final check .

i also make a pr to refactor docs with admonitions,hope it helps

Biki-das · 2022-02-25T18:23:11Z

these needs some tuning regarding the type like which one is note ,which one is a caution ,

Biki-das · 2022-02-25T18:24:17Z

docs/Configuration.md

@@ -433,11 +431,11 @@ Default: `undefined`

 This option allows the use of a custom global setup module, which must export a function (it can be sync or async). The function will be triggered once before all test suites and it will receive two arguments: Jest's [`globalConfig`](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Config.ts#L282) and [`projectConfig`](https://github.com/facebook/jest/blob/main/packages/jest-types/src/Config.ts#L347).

-_Note: A global setup module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project._
+:::note A global setup module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project.


@SimenB i think we should wrap all these Notes: into a single :::note ?

mrazauskas · 2022-02-26T06:30:03Z

docs/CLI.md

@@ -100,7 +100,7 @@ jest --update-snapshot --detectOpenHandles

 ## Options

-_Note: CLI options take precedence over values from the [Configuration](Configuration.md)._
+:::note CLI options take precedence over values from the [Configuration](Configuration.md). :::


https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier

Biki-das · 2022-02-26T07:31:06Z

The final task remaining is distinguishing where to apply tip, caution, danger and info

Biki-das · 2022-02-26T14:06:39Z

@SimenB thoughts on this one?

mrazauskas · 2022-02-27T20:22:35Z

@Biki-das This is one more style of notes which should be reworked (just a couple of examples, but there are many of them):

https://github.com/facebook/jest/blob/1125f2f4a2dad60e449d7751d70ff620fcaf3be1/docs/JestObjectAPI.md?plain=1#L22

https://github.com/facebook/jest/blob/1125f2f4a2dad60e449d7751d70ff620fcaf3be1/docs/JestObjectAPI.md?plain=1#L279

mrazauskas · 2022-02-27T20:24:40Z

docs/CLI.md

+
+:::caution
+
+the cache should only be disabled if you are experiencing caching related problems. On average, disabling the cache makes Jest at least two times slower.


Please make sure that after refactoring lines begin with capital letter:

Suggested change

the cache should only be disabled if you are experiencing caching related problems. On average, disabling the cache makes Jest at least two times slower.

The cache should only be disabled if you are experiencing caching related problems. On average, disabling the cache makes Jest at least two times slower.

mrazauskas · 2022-02-27T20:28:30Z

docs/Es6ClassMocks.md

+:::caution
+
 ```javascript
-// Note: this will fail
+// this will fail


Here it is enough to change the comment. Caution block is redundant.

mrazauskas · 2022-02-27T20:29:16Z

docs/ExpectAPI.md

+:::note
+
+In TypeScript, when using `@typess/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
+
+:::


The code example bellow is part of this Note.

mrazauskas · 2022-02-27T20:33:45Z

docs/GlobalAPI.md

+Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting.
+
+:::note
+
+The default timeout is 5 seconds.
+
+:::


I think here and in similar cases below there is no need for Note. Sounds fine a sentence.

Suggested change

Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting.

:::note

The default timeout is 5 seconds.

:::

Optionally, you can provide a `timeout` (in milliseconds) for specifying how long to wait before aborting. The default timeout is 5 seconds.

mrazauskas · 2022-02-27T20:38:06Z

docs/Troubleshooting.md

+:::note
+
+This will only work in Node.js 8+.
+
+:::


This one could be mark as History instead of Note (; Just remove it.

mrazauskas · 2022-02-27T20:40:53Z

docs/Webpack.md

-> Note: Jest caches files to speed up test execution. If you updated .babelrc and Jest is still not working, try running Jest with `--no-cache`.
+:::note
+
+Jest caches files to speed up test execution. If you updated .babelrc and Jest is still not working, try running Jest with `--no-cache`.


--clearCache sounds like better idea, or?

Suggested change

Jest caches files to speed up test execution. If you updated .babelrc and Jest is still not working, try running Jest with `--no-cache`.

Jest caches files to speed up test execution. If you updated `.babelrc` and Jest is still not working, try running `jest --clearCache`.

mrazauskas · 2022-02-27T20:42:46Z

Thanks for taking care of this. Many users will benefit, but also this is lots of work. I just went through and left few comments / suggestions. Hope these help.

Biki-das · 2022-02-28T04:17:07Z

Thanks for taking care of this. Many users will benefit, but also this is lots of work. I just went through and left few comments / suggestions. Hope these help.

thank you for the review. I will go through them and apply them.

Biki-das · 2022-02-28T04:54:34Z

@mrazauskas @SimenB i mess up a lot when merge conflicts happen , my last pr got a huge mess and i accidently closed that too and this is bad, can anyone just help me out?

Biki-das · 2022-02-28T05:05:17Z

the lint fail happen when i resolved the conflict now how do i run prettier , because this commit wont show in my git log?

SimenB · 2022-02-28T11:22:32Z

yarn lint:prettier

SimenB · 2022-02-28T11:26:43Z

docs/CLI.md

+
+:::caution
+
+clearing the cache will reduce performance.


These are sentences, so should be capitalized

SimenB · 2022-02-28T11:26:56Z

docs/CLI.md

-Force Jest to exit after all tests have completed running. This is useful when resources set up by test code cannot be adequately cleaned up. _Note: This feature is an escape-hatch. If Jest doesn't exit at the end of a test run, it means external resources are still being held on to or timers are still pending in your code. It is advised to tear down external resources after each test to make sure Jest can shut down cleanly. You can use `--detectOpenHandles` to help track it down._
+Force Jest to exit after all tests have completed running. This is useful when resources set up by test code cannot be adequately cleaned up.
+
+:::tip


Suggested change

:::tip

:::caution

SimenB · 2022-02-28T11:27:33Z

docs/Configuration.md

-_Note: Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](manual-mocks#mocking-node-modules)._
+:::note
+
+Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](manual-mocks#mocking-node-modules).


Suggested change

Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](manual-mocks#mocking-node-modules).

Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](ManualMocks.md#mocking-node-modules).

SimenB · 2022-02-28T11:27:49Z

docs/Configuration.md


-_Note: Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`._
+Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`.


Suggested change

Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`.

Built in modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`.

SimenB · 2022-02-28T11:32:22Z

docs/Configuration.md

-_Note: Each glob pattern is applied in the order they are specified in the config. (For example `["!**/__tests__/**", "**/*.js"]` will not exclude `__tests__` because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after `**/*.js`.)_
+:::note
+
+Each glob pattern is applied in the order they are specified in the config. (For example `["!**/__tests__/**", "**/*.js"]` will not exclude `__tests__` because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after `**/*.js`.)


this should be tip, the second (collectCoverage thing) should be a note

SimenB · 2022-02-28T11:32:57Z

@Biki-das I think we should do one PR per file, or this will be huge and hard to properly review

Biki-das · 2022-02-28T16:37:54Z

@SimenB closing this one , as you said seperate doc for each would be better

github-actions · 2022-04-01T00:08:11Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

facebook-github-bot added the cla signed label Feb 25, 2022

Biki-das mentioned this pull request Feb 25, 2022

refactor docs with admonitions #12499

Closed

Biki-das commented Feb 25, 2022

View reviewed changes

mrazauskas reviewed Feb 26, 2022

View reviewed changes

mrazauskas reviewed Feb 27, 2022

View reviewed changes

SimenB reviewed Feb 28, 2022

View reviewed changes

Biki-das closed this Feb 28, 2022

Biki-das reopened this Mar 1, 2022

Biki-das closed this Mar 1, 2022

Biki-das mentioned this pull request Mar 1, 2022

docs(cli): use admonitions #12525

Merged

github-actions bot locked as resolved and limited conversation to collaborators Apr 1, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore Doc refactor with Admonitions #12498

chore Doc refactor with Admonitions #12498

Biki-das commented Feb 25, 2022

Biki-das commented Feb 25, 2022

weidehai commented Feb 25, 2022

Biki-das commented Feb 25, 2022

Biki-das Feb 25, 2022

mrazauskas Feb 26, 2022

Biki-das commented Feb 26, 2022 •

edited

Loading

Biki-das commented Feb 26, 2022

mrazauskas commented Feb 27, 2022

mrazauskas Feb 27, 2022

mrazauskas Feb 27, 2022

mrazauskas Feb 27, 2022

mrazauskas Feb 27, 2022

mrazauskas Feb 27, 2022

mrazauskas Feb 27, 2022

mrazauskas commented Feb 27, 2022

Biki-das commented Feb 28, 2022

Biki-das commented Feb 28, 2022

Biki-das commented Feb 28, 2022

SimenB commented Feb 28, 2022

SimenB Feb 28, 2022

SimenB Feb 28, 2022

SimenB Feb 28, 2022

SimenB Feb 28, 2022 •

edited

Loading

SimenB Feb 28, 2022

SimenB commented Feb 28, 2022

Biki-das commented Feb 28, 2022

github-actions bot commented Apr 1, 2022


		:::caution

		the cache should only be disabled if you are experiencing caching related problems. On average, disabling the cache makes Jest at least two times slower.

	Jest caches files to speed up test execution. If you updated .babelrc and Jest is still not working, try running Jest with `--no-cache`.
	Jest caches files to speed up test execution. If you updated `.babelrc` and Jest is still not working, try running `jest --clearCache`.

	Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](manual-mocks#mocking-node-modules).
	Node modules are automatically mocked when you have a manual mock in place (e.g.: `__mocks__/lodash.js`). More info [here](ManualMocks.md#mocking-node-modules).


		_Note: Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`._
		Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`.

	Core modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`.
	Built in modules, like `fs`, are not mocked by default. They can be mocked explicitly, like `jest.mock('fs')`.

chore Doc refactor with Admonitions #12498

chore Doc refactor with Admonitions #12498

Conversation

Biki-das commented Feb 25, 2022

Biki-das commented Feb 25, 2022

weidehai commented Feb 25, 2022

Biki-das commented Feb 25, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Biki-das commented Feb 26, 2022 • edited Loading

Biki-das commented Feb 26, 2022

mrazauskas commented Feb 27, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mrazauskas commented Feb 27, 2022

Biki-das commented Feb 28, 2022

Biki-das commented Feb 28, 2022

Biki-das commented Feb 28, 2022

SimenB commented Feb 28, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SimenB Feb 28, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SimenB commented Feb 28, 2022

Biki-das commented Feb 28, 2022

github-actions bot commented Apr 1, 2022

Biki-das commented Feb 26, 2022 •

edited

Loading

SimenB Feb 28, 2022 •

edited

Loading