Docs: List all of the available widgets and their available options

[JeffersonBledsoe]

The existing widgets have various behaviours which aren't documented and require viewing the component code to see. It would be great to have a visual documentation for the available widgets and their options

[tiberiuichim]

We have the storybook setup: https://6.dev-docs.plone.org/storybook/?path=/story/edit-widgets-password--password&globals=measureEnabled:false

Basically, we need people to fill in and properly document our widgets.

Though, I don't know how good this documentation has to be. It's a good playground to test the capabilities of a widget, but if I'm writing code, I usually keep a clone of Volto, to read the code. It's best to learn and understand, I don't think there's anything wrong with that. Of course, we should document, but I feel we shouldn't be ashamed if people still read Volto's source code to understand something. Perhaps... maybe a docstring type of documentation extraction would help here. Unfortunately storybook doesn't lend itself to this.

[stevepiercy]

I agree that manually duplicating all the options of each widget into the narrative docs would be a painful exercise. If it can be automated, then I would be in full support of it.

Is there a Sphinx extension that can extract React docstrings, similar to autodoc?

Meanwhile, from our narrative docs, we should have links from each widget listed to their Storybook counterparts as a convenience to documentation reader. That will give them all they need to get by until we can automate the extraction of React docstrings.

[stevepiercy]

Also I think that the links should look like buttons, using a nifty Sphinx extension, sphinx-design. We already use it in other places in the main Plone docs.

[tiberiuichim]

@stevepiercy There is JSDoc which can extract docstrings and read React Proptypes (static types annotations of component parameter). Older Volto code used to be more thorough with these annotations, but since there's no tool to take advantage of having them, they've not been too well maintained.

[stevepiercy]

A quick DuckDuckGo search turned up something that might do what we like.

https://pypi.org/project/sphinx-js/

Install that extension, write JSDoc docstrings, then make html. Done.

A good example using most of sphinx-js’s functionality is the Fathom documentation. A particularly juicy page is https://mozilla.github.io/fathom/ruleset.html. Click the “View page source” link to see the raw directives.

Would one of you like to try it out on a new branch, then open a PR against master, then Netlify will generate an automatic preview?

[JeffersonBledsoe]

@stevepiercy I started looking into this by setting up sphinx-js in #3683, but I'm having some issues trying to get it recursively find all doc strings. In the sphinx output, I can see lines similar to ERROR: Unable to parse a tag's type expression for source file /Users/jefferson/projects/packages/volto/src/helpers/FormValidation/FormValidation.js, so I know it's finding the files, but later on I get:

Sphinx error:
jsdoc found no JS files in the directories ['/Users/jefferson/projects/packages/volto/src']. Make sure js_source_path is set correctly in conf.py. It is also possible (though unlikely) that jsdoc emitted invalid JSON.

If I remove the jsdoc_config_path in, it finds the JSDoc comments that are in the root of the src folder, but it doesn't recursively search the other files then. I don't suppose you've any idea what's happening?

Additionally, it doesn't seem to support Python 3.10 at the moment. 3.9 works fine for me locally if you want to try it.

[stevepiercy]

For Python 3.10, see https://github.com/mozilla/sphinx-js/issues/186. Until that is resolved, we cannot use this extension, as we do not want to constrain ourselves to Python<3.10. I was able to run it on Python 3.10 per this comment: https://github.com/mozilla/sphinx-js/issues/186#issuecomment-1005638042

I can confirm I see the same error as you do regarding "jsdoc found no JS files". I'm not sure what to try next.