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

Jump to bottom

Transition README Docs to Docusaurus-Netlify Setup #641

Merged
merged 28 commits into from
Dec 2, 2023
Merged

Transition README Docs to Docusaurus-Netlify Setup #641

merged 28 commits into from
Dec 2, 2023

Conversation

aryaemami59
Copy link
Contributor

This PR kickstarts migrating the existing documentation from a README file to a Netlify site using Docusaurus.

@codesandbox-ci CodeSandbox CI
Copy link

codesandbox-ci bot commented Nov 21, 2023 •
edited
Loading

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 0bc5987:

Sandbox Source
Vanilla Typescript Configuration

@aryaemami59
Add "ts-node" to tsconfig.json
bc12741
@aryaemami59
Add examples folder to .gitignore
5cd9946
@aryaemami59
Remove remark-typescript-tools from dependencies
3c11315 
- Remove remark-typescript-tools as it is incompatible with docusaurus v3.
- Replace it with gulp-preserve-typescript-whitespace and some utility functions to achieve the same results.
- This happened to work out somewhat even better since the build time for docs is reduced.
- It also simplifies things since we go straight from TS -> MDX instead of MDX -> TS -> MDX.
@aryaemami59
Add link components
857d378 
- Copy CSS from Redux-toolkit.
- Add external and internal link components for reusability and performance.
- Add introduction section from README to website.
- Move static assets to docs folder.
- Replace markdown links with component links.
  -  This was done because docusaurus has made some improvements with regards to links (preloading, prefetching, etc) as well as broken link detection.
@aryaemami59
Add eslint overrides config for examples folder
8cda3fe
@aryaemami59
Fix tsconfig for examples folder
89b917e
@aryaemami59
Add jsx files to "clean:examples"
c7cf61a
@aryaemami59
Add tsx files to gulp task
612b392
@aryaemami59
Remove single details closing tag from README
27ef4bf 
- During previous commits, parts of the example for `createStructuredSelector` was accidentally removed. They are added back to README.
- Fix minor formatting issues in README.
@aryaemami59
Add remaining material from README to docs
8e5646a 
- Add code example files. These will get transpiled to code blocks in MDX during the build step.
- This ensures we maintain accuracy in code examples and also prevents unnecessary redundancies by providing a single source of truth.
- Fix the sidebar so that it somewhat resembles the RTK documentation.
- Internal and external links still need to be converted to JSX.
@aryaemami59
Fix InternalLinks to props.
7c2fa5a
@markerikson
Copy link
Contributor

Looking at this, and I'm rather confused by the setup approach here:

  • Why are we using Gulp at all for anything? Are there other tools / approaches?
  • What broke with remark-ts-tools in Docusaurus v3?
  • Do we actually need the examples as separate TS files?

Couple nits on the package.json setup:

  • The nested build:example commands are confusing
  • Naming-wise, I'd prefer to have "docs:$COMMAND" rather than "$COMMAND:docs"
  • Given that we use Yarn for package management, let's switch all npm run usages to yarn run

@aryaemami59
Copy link
Contributor Author

Looking at this, and I'm rather confused by the setup approach here:

  • Why are we using Gulp at all for anything? Are there other tools / approaches?
  • What broke with remark-ts-tools in Docusaurus v3?
  • Do we actually need the examples as separate TS files?

Couple nits on the package.json setup:

  • The nested build:example commands are confusing
  • Naming-wise, I'd prefer to have "docs:$COMMAND" rather than "$COMMAND:docs"
  • Given that we use Yarn for package management, let's switch all npm run usages to yarn run

Yeah I'm still trying to figure it all out, so a lot is going to change. To answer some of your questions:

  • I'm using gulp-preserve-typescript-whitespace which allows me to compile TS files while preserving empty lines (currently trying to figure out a better solution).
  • Not sure what broke it, but there is an issue filed for it already Support for Docusaurus v3 phryneas/remark-typescript-tools#13
  • Putting examples in separate TS files makes it easier to convert each one to markdown codeblocks, it also helps knowing each example can be run independently.
  • I will fix the other issues related to package.json, tbh I was too sleep deprived when I wrote them :)

Another thing to note about remark-typescript-tools is that while it is an amazing tool and you guys use it in RTK docs, it's necessary for that project, since from the get go, the examples were written in markdown and not in TS files. So you ended up parsing markdown to TS, then TS to JS, then JS back to markdown. Which is why bulding the docs in RTK can sometimes take almost 10 minutes. If you have the examples in TS files from the beginning, you only have to do TS -> JS -> MDX instead of MDX -> TS -> JS -> MDX. That's also another reason why I set it up this way so we don't have to do what you guys did in RTK.

@markerikson
Copy link
Contributor

I'll admit this is sort of a weird prejudice, but I don't like Gulp :) part of it is that it "feels" very outdated given the existence of newer tools, and I had a bad experience trying to rip it out of a project several years back.

Are there any other tool pipelines that would work here instead of Gulp?

Side note: could we also move the examples to a docs/examples/ subfolder?

@aryaemami59
Copy link
Contributor Author

I'll admit this is sort of a weird prejudice, but I don't like Gulp :) part of it is that it "feels" very outdated given the existence of newer tools, and I had a bad experience trying to rip it out of a project several years back.

Trust me, I know. I don't like it either. Right now I'm trying to figure out if there are other ways.

Side note: could we also move the examples to a docs/examples/ subfolder?

I was just thinking the same thing.

@aryaemami59
Move examples folder into docs/examples
2edccc2
@aryaemami59
Replace npm run commands with yarn
4181264
@aryaemami59
Replace gulp-preserve-typescript-whitespace with compileExamples.ts
1732551 
- Remove all the `gulp` related dependencies.
- Add `compileExamples.ts` which accomplishes the same thing with `ts-node`.
@aryaemami59
Slightly modify ExternalLinks to allow for more customization
7d6db5a
@aryaemami59
Fix minor grammar mistake in README
fc73039
@aryaemami59
Add insertCodeExamples.ts
ac07be8 
- Add `insertCodeExamples` to allow insertion of code examples into MDX files.
- Rename some of the example files.
-  Replace markdown links with JSX links.
@aryaemami59
Remove nested examples:build commands
fd601d6 
- Remove extraneous dependencies
- Add `ts-node` to devDependencies
- Add `prettier` and `rimraf` to devDependencies
- Simplify the commands inside `website/package.json`
@aryaemami59 aryaemami59 marked this pull request as ready for review November 26, 2023 01:48
@aryaemami59 aryaemami59 mentioned this pull request Nov 26, 2023
Merged
14 tasks
@aryaemami59 aryaemami59 marked this pull request as draft December 1, 2023 23:50
@markerikson markerikson marked this pull request as ready for review December 2, 2023 03:08
@markerikson
Copy link
Contributor

Okay, let's get the initial setup in so I can iterate on config

@markerikson markerikson merged commit 810d634 into reduxjs:master Dec 2, 2023
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@aryaemami59 @markerikson