Created documentation for configuration (ArtiomTr#84)

Author: ArtiomTr

.vscode/settings.json

@@ -1,5 +1,8 @@
 {
     "editor.codeActionsOnSave": {
         "source.fixAll": true
+    },
+    "files.associations": {
+        "*.md": "mdx"
     }
 }

action.yml

@@ -24,7 +24,7 @@ inputs:
         default: emoji
     annotations:
         required: false
-        description: 'What type of annotations show. Options: none, all'
+        description: 'What type of annotations show. Options: none, coverage, failed-tests, all'
         default: all
     package-manager:
         required: false

docs/assets/coverage-annotation-example.jpg

@@ -38,6 +38,8 @@ declare module '@mdx-js/react' {
         [key in ComponentType]?: React.ComponentType<{
             children: React.ReactNode;
         }>;
+    } & {
+        [key: string]: React.ComponentType;
     } & {
         a?: React.ComponentType<{ href: string }>;
         h1?: React.ComponentType<HeadingProps>;

docs/assets/failed-test-annotation-example.jpg

@@ -50,7 +50,7 @@ export const Header = ({ links }: HeaderProps) => {
                     display="flex"
                     maxW="container.lg"
                 >
-                    <Link href="/">
+                    <Link href="/" passHref>
                         <Logo
                             className={classes['logo']}
                             color="var(--chakra-colors-brand-600)"

docs/mdx.d.ts

@@ -1,4 +1,4 @@
-import { Flex, Heading, HeadingProps } from '@chakra-ui/react';
+import { Flex, Heading, HeadingProps, useStyleConfig } from '@chakra-ui/react';
 import { HashIcon } from '@primer/octicons-react';
 import Link from 'next/link';
 import React from 'react';
@@ -7,19 +7,34 @@ import classes from './MarkdownHeading.module.scss';
 
 export type MarkdownHeadingProps = HeadingProps;
 
-export const MarkdownHeading = ({ id, ...props }: MarkdownHeadingProps) => (
-    <Link href={`#${id}`}>
-        <Flex
-            borderColor="gray.150"
-            borderBottomWidth="thin"
-            className={classes['heading']}
-            alignItems="center"
-            justifyContent="flex-start"
-            marginY="3"
-        >
-            <span className={classes['heading__anchor']} id={id} />
-            <HashIcon size={24} className={classes['heading__icon']} />
-            <Heading {...props} />
-        </Flex>
-    </Link>
-);
+export const MarkdownHeading = ({
+    id,
+    children,
+    ...props
+}: MarkdownHeadingProps) => {
+    const { fontSize } = useStyleConfig('Heading', props);
+
+    return (
+        <Link href={`#${id}`}>
+            <Flex
+                borderColor="gray.150"
+                borderBottomWidth="thin"
+                className={classes['heading']}
+                alignItems="center"
+                justifyContent="flex-start"
+                marginY="3"
+            >
+                <span className={classes['heading__anchor']} id={id} />
+                <HashIcon size={24} className={classes['heading__icon']} />
+                <Heading
+                    sx={{
+                        '--children-font-size': fontSize as string,
+                    }}
+                    {...props}
+                >
+                    {children}
+                </Heading>
+            </Flex>
+        </Link>
+    );
+};

docs/src/components/Header.tsx

@@ -11,6 +11,7 @@ import React from 'react';
 import { Code } from './Code';
 import { MarkdownHeading } from './MarkdownHeading';
 import { MdLink } from './MdLink';
+import { ResponsiveImage } from '../ResponsiveImage';
 
 export const components: Components = {
     h1: (props) => <MarkdownHeading as="h1" size="2xl" {...props} />,
@@ -25,5 +26,11 @@ export const components: Components = {
     a: MdLink,
     p: Text,
     code: Code,
-    inlineCode: (props) => <ChakraInlineCode {...props} />,
+    inlineCode: (props) => (
+        <ChakraInlineCode
+            fontSize="var(--children-font-size, var(--chakra-fontSizes-sm))"
+            {...props}
+        />
+    ),
+    ResponsiveImage,
 };

docs/src/components/markdown/MarkdownHeading.tsx

@@ -0,0 +1,117 @@
+---
+title: Configuration
+description: Documentation for the action's configuration. Described all inputs with examples.
+---
+
+import CoverageAnnotationExample from 'assets/coverage-annotation-example.jpg';
+import FailedTestAnnotationExample from 'assets/failed-test-annotation-example.jpg';
+
+# Configuration
+
+Jest Coverage Report action's configuration is created in the same way as for [any other GitHub action](https://www.github.com/features/actions).
+
+## github-token
+
+GitHub token. Required parameter. By default, you can use standard GitHub-provided token: `${{ secrets.GITHUB_TOKEN }}`. Example:
+
+```yaml
+- uses: artiomtr/jest-coverage-report-action@v2
+    with:
+        github-token: \${{ secrets.GITHUB_TOKEN }}
+```
+
+## threshold
+
+If you want to set minimal accepted coverage for the PR, you can pass and optional parameter threshold.
+
+For example, if you want to reject every pull request, with total line coverage less than 80%:
+
+```yaml
+- uses: artiomtr/jest-coverage-report-action@v2
+    with:
+        threshold: 80 # if coverage < 80%, action will fail
+```
+
+## working-directory
+
+If you want to run this action in custom directory, specify `working-directory`:
+
+```yaml
+with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    working-directory: <dir>
+```
+
+## test-script
+
+By default, action will run this command, to extract coverage:
+
+```bash
+npx jest --silent --ci --coverage --testLocationInResults --json --outputFile="report.json"
+```
+
+If you're not satisfied with default behaviour, you can specify your own command, by passing custom option `test-script`.
+
+<!-- TODO: replace link -->
+
+**⚠ IMPORTANT: The test script must generate output in a specific format. For more information, see [docs](https://github.com/ArtiomTr/jest-coverage-report-action#customizing-test-script).**
+
+For instance, if you want to run `test:coverage` npm script:
+
+```yaml
+with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    test-script: npm run test:coverage
+```
+
+## icons
+
+If you don't satisfied with the standard icons, you can replace them with `icons` input. Example:
+
+```yaml
+with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    icons: ascii
+```
+
+Available options: `emoji` (standard), `ascii`, `unicode`.
+
+## annotations
+
+Annotations are enabled by default. To disable them, specify `annotations: none`. For instance:
+
+```yaml
+with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    annotations: none
+```
+
+If you want to enable only specific annotations, you can specify following choices:
+
+### `annotations: coverage`
+
+<ResponsiveImage width="100%" images={CoverageAnnotationExample.images} />
+
+### `annotations: failed-tests`
+
+<ResponsiveImage width="100%" images={FailedTestAnnotationExample.images} />
+
+### package-manager
+
+By default, action uses [npm](https://github.com/npm/cli#readme) package manager. But, if you want to use [yarn](https://github.com/yarnpkg/berry#readme), simply set `package-manager: yarn` option:
+
+```yaml
+with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    package-manager: yarn
+```
+
+### skip-step
+
+If you've installed dependencies in previous step, or you already have `report.json` file, you can skip `install` or `all` steps. For instance:
+
+```yaml
+with:
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+    skip-step: install
+```

docs/src/components/markdown/components.tsx

@@ -15,7 +15,8 @@
         "jsx": "preserve",
         "baseUrl": ".",
         "paths": {
-            "layouts/*": ["src/components/layouts/*"]
+            "layouts/*": ["src/components/layouts/*"],
+            "assets/*": ["assets/*"]
         }
     },
     "include": ["next-env.d.ts", "mdx.d.ts", "**/*.ts", "**/*.tsx"],