cursorless
cursorless copied to clipboard
cursorless-dev
Added per language scope support docs
Checklist
- [/] I have added tests
- [x] I have updated the docs and cheatsheet
- [/] I have not broken the cheatsheet
@pokey Looks like meta updater have some problem on windows. If I run the lint:meta script on my own computer it works fine and works fine on Linux and mac, but windows on ci is failing. Probably have something to do with line endings?
Also I would prefer to remove the unsupported scope facet level. Since there's isn't really any difference between explicitly saying unsupported and not specifying the level at all.
I would argue for keeping unsupported. Otherwise there's no way to know if it is unspecified because it's unsupported or if we just haven't gotten around to indicating its support level yet
Yes I'm just doubting that we are ever going to actually do that :p But sure let's keep it for now.
Yes I'm just doubting that we are ever going to actually do that :p
Sorry not sure I'm following: doubting whether we'll do what?
Yes I'm just doubting that we are ever going to actually do that :p
Sorry not sure I'm following: doubting whether we'll do what?
Getting around to actually going through all scope facets and specifying unsupported.
Getting around to actually going through all scope facets and specifying unsupported.
Exactly. That's why it's important to have the ability to distinguish between unsupported and just not having been specified yet. If we just take unspecified to mean it's unsupported, we won't be able to tell which ones are actually unsupported and which we just haven't gotten around to yet
Eg we could render the missing ones with a question mark in the docs to encourage people to contribute, and so they don't get the false impression it's not supported when really it is
Not sure but I'm not sure it's a good idea to use meta-updater for generating this .md file anyway. My instinct would be to do that during web build step. Is there some reason to prefer checking this file into source control?
I always prefer if documentation is in markdown. If I need to navigate to a webpage to read the docs I'm probably not gonna do it as often.
Yeah but this file is huge. Are you really going to read this file anyway? I had thought that the tables were supposed to be more for users, and that contributors would just look at the source code
I guess that works as well. Where do you want this placed instead?
Maybe we just generate it into docs folder during website build step and add that to gitignore? That's what we used to do with our api docs
I don't believe we do anything like that today. On second thought, though, we should prob do it with an MDX react component that imports the scope support tables
That sounds reasonable. Have you done anything like that before or do you have some documentation I could look at how to do that with docusaurs?
Just Google docusaurus MDX. We have some MDX stuff in our next.js root site as well. Look for files ending in mdx
If you get stuck let's discuss at meetup
I was thinking more where to put the files in how to get docusaurus to read them. Just putting a mdx file in cursorless-org-docs/src appears to do nothing for the main docs page. Not like a markdown file that is automatically added to the menu.
You just put it where you'd put a markdown file but use mdx file ending. Then import react component and use it. The react component would import language support info from common and use it to render support table
Oh you're support to put it in the root/docs folder? How is it supposed to get access to the Cursorless common package from there? I'm afraid I don't really understand the build config here.
Have a look at our other mdx files. As mentioned, they're in the next js part of our site but should be similar
Our other mdx files are all in packages/cursorles-org. That is why I tried putting this new file in packages/cursorles-org-docs. Importing from a package outside of the package's folder feels like a bad pattern. I think we need to have a session about this.
@pokey documentation is now moved into the packages folder and we are using a proper react component with a per language mdx file.
docusaurus start works fine, but docusaurus build fails with the following errors :
Error: Docusaurus server-side rendering could not render static page with path /user/languages/yaml/ because of error: Cannot read properties of undefined (reading 'jsx')
@pokey documentation is now moved into the packages folder and we are using a proper react component with a per language mdx file.
docusaurus startworks fine, butdocusaurus buildfails with the following errors :Error: Docusaurus server-side rendering could not render static page with path /user/languages/yaml/ because of error: Cannot read properties of undefined (reading 'jsx')
After a merge, this is working fine for me, both locally and in CI, so I guess it just went away 🤷♂️. But I guess worth confirming that it works now locally for you
This is very cool, but I wonder if it is premature. I worry users might see the "supported" list at the top and assume everything else is unsupported. Maybe we should wait until we've migrated our recorded test fixtures using https://github.com/cursorless-dev/cursorless/issues/2390? I don't want this to pile up merge conflicts tho, esp since you've gotten mdx working in our docs site
I wonder if there's a way to ship this in a way that these lang pages are harder to find / hidden