📝 Enable codeblock TS transpilation

[Shrugsy]

• Set up ability to transpile codeblocks to show a TS & JS tab
• Convert 'WritingTests' page to use transpiled codeblocks
• Update snippets on 'WritingTests' page

---

name: 📖 New/Updated Documentation Content
about: Updating content in an existing docs page

PR Type

Does this PR add a new page, or update an existing page?

Updates an existing page (Writing Tests).
Also adds the ability to transpile doc codeblocks from TS to show both TS & JS tabs.

Checklist

• Is there an existing issue for this PR?
  • [Docs] Update all code blocks to toggle between TS and JS syntax #4112 (does not complete the issue)
• Have the files been linted and formatted?

What docs page is being added or updated?

• Section: Usage
• Page: Writing Tests

For Updating Existing Content

What updates should be made to the page?

• Show both TS & JS tabs for codeblocks

Do these updates change any of the assumptions or target audience? If so, how do they change?

Yes - now targeted to accommodate both TS & JS users

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 886999e:

Sandbox	Source
Vanilla	Configuration
Vanilla Typescript	Configuration

[netlify]

✅ Deploy Preview for redux-docs ready!

Name	Link
🔨 Latest commit	886999e
🔍 Latest deploy log	https://app.netlify.com/sites/redux-docs/deploys/62bda9b160075f0007123e9c
😎 Deploy Preview	https://deploy-preview-4149--redux-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[timdorr]

We shouldn't have the docs path contain any JS files. Instead, can that tooling live in the website path, which is already a package, and just reach out to docs to grab the code?

[Shrugsy]

@timdorr

We shouldn't have the docs path contain any JS files. Instead, can that tooling live in the website path, which is already a package, and just reach out to docs to grab the code?

@phryneas has advised:

Could only move it up to the parent folder. It's the normal node module resolution algorithm. Will look up the directory tree into every node module folder, but not left and right

So theoretically it might be possible for all of the packages to stick under website/package.json if the entire docs directory was moved into website

[markerikson]

I definitely don't want to move the docs folder if at all possible.

[Shrugsy]

@timdorr @markerikson:
@phryneas released an update for remark-typescript-tools, allowing the transformation of the virtual files paths, which in turn allows the docs config to mix in with website (by allowing docs content to resolve node_modules in a sibling directory).

The resultant changes to the docs directory is that code snippets will be written in a manner that enables the TS transpilation & TS/JS tab generation, while all config & installed packages can live under website instead.

I've converted the 'writing tests' page to transpile the codeblocks, which can be previewed here: https://deploy-preview-4149--redux-docs.netlify.app/usage/writing-tests

@timdorr I recommend specifically having a look at the snippet changes involved in WritingTests.mdx to get an idea of how that will affect someone looking at the 'raw markdown'.

Note that the benefit here is more than just creating a TS/JS tab - It also ensures that the snippet is actually valid code. I fixed up a couple of mistakes/missing imports while converting this page thanks to that.

[markerikson]

Looks pretty good to me!

Do we have full Netlify caching turned on for the core docs site atm, the way we do for RTK?

[Shrugsy]

Do we have full Netlify caching turned on for the core docs site atm, the way we do for RTK?

I have no idea personally. I can say that the netlify build did seem fast, but that could be because only this one page has any transpilation going on so far

[timdorr]

@timdorr I recommend specifically having a look at the snippet changes involved in WritingTests.mdx to get an idea of how that will affect someone looking at the 'raw markdown'.

Well, the good news is GitHub knows exactly what mdx is and displays it the same as plain Markdown: https://github.com/Shrugsy/redux/blob/docs/enable-ts-codeblock-transpilation/docs/usage/WritingTests.mdx

[Shrugsy]

Well, the good news is GitHub knows exactly what mdx is and displays it the same as plain Markdown: https://github.com/Shrugsy/redux/blob/docs/enable-ts-codeblock-transpilation/docs/usage/WritingTests.mdx

Yeah good point. Basically the thing I want to point out as a 'potential concern' is that the raw markdown will include portions in the snippet that are intended for use as virtual files, but not intended to be included on the final snippet (anything marked as noEmit isn't meant to be displayed)

For efficiency's sake, these may often be be partial pieces of code that aren't intended to make much sense for someone reading the docs, but are created to have the correct type signature, and may only include the necessary content that the relevant snippet file wants to import

e.g. below

[markerikson]

Oh hey, I completely forgot this was here :)

@Shrugsy: any chance you could rebase this against the changes on master? Unfortunately this collides with the changes I just made to WritingTests.md and upgrading to DS 2.21, so you may end up needing to rework it.

[Shrugsy]

Oh hey, I completely forgot this was here :)

@Shrugsy: any chance you could rebase this against the changes on master? Unfortunately this collides with the changes I just made to WritingTests.md and upgrading to DS 2.21, so you may end up needing to rework it.

@markerikson FYI - I've rebased this branch and adjusted for the collisions.

FYI - I've made some (admittedly opinionated) adjustments to WritingTests while updating the codeblocks for transpilation.

Rather than exporting renderWithProviders as render, and re-exporting everything from RTL, I've kept it as renderWithProviders, and not re-exported anything from RTL. I think it's confusing for users to set it up the other way, adding indirection as to where their test functions are coming from, and what they do. With how well automatic imports are already handled, I don't see a good reason to re-export from RTL. Plus, because of automatic imports, overriding render with a separate function by the same name only provides additional opportunities to accidentally import the wrong one, whereas keeping it as renderWithProviders maintains a clear distinction.

[Shrugsy]

For clarity - what this MR really does is allow for the documentation to:

• Link to docblocks within documentation, effectively using code comments as documentation (see https://github.com/phryneas/remark-typescript-tools#linkdocblocks)

• Transpile codeblocks, adding the ability for readers to swap between TS/JS tabs, and also to compile-check the codeblocks themselves (a few typos & missing imports were fixed in this PR thanks to this). See https://github.com/phryneas/remark-typescript-tools#transpilecodeblocks

e.g.

Before	After

[markerikson]

SWEEEEET let's do this!