[docs] Bootstrap docs/landing page site

bharatkashyap commented 1 year ago

Deploy preview:

Partially fixes #477 Fixes #488

render[bot] commented 1 year ago

Your Render PR Server URL is https://toolpad-pr-542.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-cagvt9j19n0fr4mh1a10.

render[bot] commented 1 year ago

Your Render PR Server URL is https://toolpad-pr-542.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-cajp6350mal285rl1qig.

Janpot commented 1 year ago

@bharatkashyap Ok, this took some time to sort out. It's not finished, but at least there's something on the screen now.

The @mui/monorepo is a github dependency. yarn installs its dependencies so we can use things from e.g. the ./scripts folder. For the docs we are importing code from some of its workspaces. These are not installed in node_modules since yarn doesn't install workspaces of dependencies. Therefore anything trying to resolve them using the node module resolution algorithm (webpack) will fail to find them. Also their transitive dependencies are not installed. The workaround used in MUI X is to alias the package identifiers to their workspace inside the @ui/monorepo and by making sure that these packages are compiled. I've removed the aliasing from babel config and added it to webpack. This really is a task for webpack, not for babel. For this to work we must always make sure that:

Any transitive dependencies for the monorepo are installed in the docs workspace (e.g. react or @emotion/styled)
We specifiy the paths to the workspace packages correctly in next.config.json.

Janpot commented 1 year ago

@bharatkashyap Before we invest more time in the docs content, we need to sort out the FOUC. if it can't be solved, then I don't want to continue with this brittle setup.

bharatkashyap commented 1 year ago

@Janpot The .md imports with resource queries seem to giving module unresolved errors:

Janpot commented 1 year ago

I had some moderate success adding ./docs/.eslintrc.js with

const path = require('path');

const MONOREPO_PATH = path.resolve(__dirname, './node_modules/@mui/monorepo');

module.exports = {
  settings: {
    'import/resolver': {
      webpack: {
        config: {
          resolve: {
            alias: {
              docs: path.resolve(MONOREPO_PATH, './docs'),
            },
            // extensions: ['.js', '.json', '.jsx', '.ts', '.tsx', '.d.ts'],
          },
        },
      },
    },
  },
};

But other resolver errors start popping up. These can be fixed with uncommenting the // extensions: ... line. But that breaks the ?@mui/markdown again. Not going to spend more time on this. If you can't get this debugged, let's just add an override in our ./.eslintrc.js to exclude those:

// ...
  overrides: [
    {
      files: ['./docs/**/*'],
      rules: {
        'import/no-unresolved': ['error', { ignore: ['\\.md\\?@mui/markdown$'] }],
      },
    },
// ...

Also, it looks like you can remove ./docs/src/modules/utils/findPages.js.

bharatkashyap commented 1 year ago

There seems to be an unrelated error (particular to this PR) that is causing the build to fail:

render[bot] commented 1 year ago

Your Render PR Server URL is https://toolpad-pr-542.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-caurrcrru51tqnfp2ckg.

Janpot commented 1 year ago

@oliviertassinari We had trouble integrating the same version of @mui/monorepo as MUIX yesterday. Maybe that's something to be solved in this PR still, to avoid the technical debt?

edit

We tried out this change and it worked for us. For some reason MUIX setup understands the packages/... alias and I can't figure out why.

Its root tsconfig.json baseUrl points to its own root, so packages/... should resolve to the packages folder in mui-x repo according to this alias (docs tsconfig.json extends from this and doesn't override the baseUrl)
Its root babel config also points to its own package folder
in the webpack config in next.config.js there is no relevant alias, in the docs babel.config.js neither

oliviertassinari commented 1 year ago

@Janpot Sounds good, there are still a lot of issues we could fix on this PR 😁. To list a few:

[x] https://deploy-preview-542--mui-toolpad-docs.netlify.app/toolpad/ is not server-side generated, it only works client-side

[ ] We are missing the product picker in

bharatkashyap commented 1 year ago

Builds are failing on this PR, specifically:

Error: Cannot find module '@mui/utils/package.json'
@mui/toolpad-app: [build:*typings] Require stack:
@mui/toolpad-app: [build:*typings] - /tmp/mui-toolpad/packages/toolpad-app/scripts/typings.ts

Commenting out this line seems to make them work. I think that @mui/utils being a dependency of the new docs package is causing some interference with how the monorepo packages get installed.

Janpot commented 1 year ago

Looks like @mui/toolpad-app is missing a dependency on @mui/utils?

bharatkashyap commented 1 year ago

Looks like @mui/toolpad-app is missing a dependency on @mui/utils?

Yes, this was the case. Fixed after adding this dependency to toolpad-app/package.json

render[bot] commented 1 year ago

Your Render PR Server URL is https://toolpad-pr-542.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-cb63dbcgqg45s1o6e7rg.

mui / mui-toolpad

[docs] Bootstrap docs/landing page site #542