Handle code samples in Volto and Seven

[stevepiercy]

Code samples in Volto might not be linted or correct. We need to ensure they are both linted and functional.

---

Yeah, both the original and modified code samples don't pass linting. Here's what I did.

1. Check out the Volto repo.

2. Run the following command to install it and its tooling from the repo's root.

   make install
   

3. Create a scratch file with the snippet, such as docs/source/blocks/editcomponent.jsx.

   import { SidebarPortal } from '@plone/volto/components';
   
   const Edit = (props) => {
     const { selected } = props;
     return (
       {/* [....] */}
       <SidebarPortal selected={selected}>
         {/* [....] */}
       </SidebarPortal>
       {/* [....] */}
     )
   };
   

4. Run the following command.

   pnpm lint docs/source/blocks/editcomponent.jsx
   

   /Users/stevepiercy/projects/Plone/documentation/submodules/volto/docs/source/blocks/test.jsx
     7:19  error  Parsing error: ')' expected
   
   ✖ 1 problem (1 error, 0 warnings)
   
    ELIFECYCLE  Command failed with exit code 1.
   

You can also run other lint commands.

pnpm prettier docs/source/blocks/test.jsx
pnpm stylelint docs/source/blocks/test.jsx

In conclusion, when neither the original nor modified code sample passes quality control, then we shouldn't change it.

---

Just for giggles, I let PyCharm's AI fix the code. It yielded the following code.

import { SidebarPortal } from '@plone/volto/components';

const Edit = (props) => {
  const { selected } = props;
  return (
    <>
      {/* [....] */}
      <SidebarPortal selected={selected}>
        {/* [....] */}
      </SidebarPortal>
      {/* [....] */}
    </>
  )
};

I then ran it through Volto's linters.

import { SidebarPortal } from '@plone/volto/components';

const Edit = (props) => {
  const { selected } = props;
  return (
    <>
      {/* [....] */}
      <SidebarPortal selected={selected}>{/* [....] */}</SidebarPortal>
      {/* [....] */}
    </>
  );
};

---

For @sneridagh, code samples that don't pass quality control has been a problem in Volto docs that we've ignored for too long. Here's one way to address it.

1. Create a .jsx file with the same name as the .md file, such as docs/source/blocks/editcomponent.jsx.
2. Move all code samples into this file.
3. Replace the code sample in .md with a literalinclude directive.

Now you can run Volto linters on the file.

Alternatively:

1. Same.
2. Copy, not move, the code sample into the .jsx file.
3. Adopt a convention for documentation authors, where we use MyST % comment and JSX {/* comment */} comments respectively in .md and .jsx files that cross references each example. For example: .md

   % ex-01
   

   .jsx

   {/* ex-01 */}
   

Is either method worth adopting?

Ultimately I'd love to run something similar to doctests and manuel for Python in documentation code samples, but for JS and JSX.

Originally posted by @stevepiercy in https://github.com/plone/volto/pull/7115#discussion_r2118298349

[sneridagh]

@stevepiercy this is killer... if we cannot automate, it is a deal breaker from my point of view.

[stevepiercy]

I got this from a fellow documentarian that looks like a promising way to run linters on JS and JSX code samples inside the MyST file, not as separate files. Just set up our Volto linters, then use a Python subprocess to run the lint commands.

https://github.com/kai687/sphinxawesome-codelinter

[stevepiercy]

I think I'll break this issue into two.

I haven't tried setting up the linters, but I think it is possible.

For testing JavaScript code snippets, we could use JSFiddle or other JavaScript playground where appropriate. We can also add reference links to the Storybook where applicable. Does anyone use such a playground that can demo any existing Volto snippet in the docs?

[stevepiercy]

I tried out https://github.com/kai687/sphinxawesome-codelinter. It's extremely slow, taking 15:17 to lint only the JSX code blocks. It also doesn't actually lint. I filed an issue at https://github.com/kai687/sphinxawesome-codelinter/issues/544.

I'm inclined to close this issue, as I just don't think it's possible to lint, format, or run JavaScript or React code snippets in narrative Sphinx documentation. Maybe there will be an easy to use tool in the future, or one exists that I don't know about. Maybe Storybook can fill in the gaps.