Integrate plone.api docs into Plone 6 Documentation

[stevepiercy]

See https://github.com/plone/documentation/issues/1178

The Plone 6 Documentation Team has already integrated Volto docs, and now we're coming for plone.api. 😁

The Volto development team wanted to keep their docs together with code, build a standalone set (at least temporarily), and integrate them into the main Plone 6 Documentation.

Does the plone.api team wish to do the same as the Volto team?

See also:

• https://community.plone.org/t/plone-6-documentation-ready-for-contributions/14741
• https://community.plone.org/t/plone-6-documentation-adds-volto-frontend-docs-automatic-deployments/14786

[ksuess]

The integration is in preparation. Please see https://github.com/plone/plone.api/pull/469. The changes are minimal invasive: No conversion to myST markdown. The documentation of plone.api is expected to be stable. So a conversion to myST markdown, which will be the slang of new Plone 6 documentation, would be a waste of resources.

The preview of the integrated plone.api documentation is available on https://6.dev-docs.plone.org/plone.api/user.html#user-get-roles-example.

[ksuess]

Hi maintainers If a conversion from restructuredText to myST markdown is preferred: I prepared a conversion script in branch 'conversion-to-myst-markdown': https://github.com/plone/plone.api/compare/integration-in-plone-docs-6...conversion-to-myst-markdown?expand=1 Run with make conversion-to-myst /cc @stevepiercy

[stevepiercy]

I would not call it a waste of resources. It does take time, but there is an automatic conversion tool that does a good job, and there might be some tweaks needed after a conversion. It is some effort, but usually not enough to be a deal breaker.

A conversion to MyST would also mean that it would be harder to track the history of files because they would be renamed.

The advantages include the ability to use Markdown, CommonMark, and reStructuredText as needed. It is also what the rest of the main docs are going to do.

See the conversation in plone.restapi.

[ksuess]

The conversion is already prepared and of course optional. It runs the official conversion script rst to myST and a custom script that corrects cross references in Python files to documentation. To see the preview of the build documentation, check out the branch 'conversion-to-myst-markdown', run make conversion-to-myst and open _build/plone6docs/html/index.html in a browser. You see the documentation build from converted myST files.

@stevepiercy, use it in plone.restapi with your additional tweaks, if you want. See the link in my earlier comment.

[stevepiercy]

@ksuess is this the file?

https://github.com/plone/plone.api/compare/integration-in-plone-docs-6...conversion-to-myst-markdown?expand=1#diff-dbf14a6a2608e1f9ad6a9a38932559a98b6c8464297691013d7a04a5af961427

What does it actually do? I'm not great at regex, but I think it looks for things like this:

:ref:`moo_cow`

and replaces them with:

{ref}`moo-cow`

Is that correct? In any case, it would be helpful to have a comment in that script that shows an example.

Also if you think that this is a common thing that would improve rst-to-myst, I would encourage you to submit a pull request to the project. The maintainers are very responsive and helpful.

[ksuess]

Hi @mauritsvanrees The conversion from restructuredText to myST markdown of the documentation files is of course optional. We use MyST in new Plone 6 documentation and also since short in Volto documentation. Do you want to stay with restructuredText or let me do the conversion? It's easy to learn.

More info about MyST markdown can be found in Plone 6 documentatio contributers guide: https://6.dev-docs.plone.org/contributing/writing-docs-guide.html

[mauritsvanrees]

@ksuess I would say go ahead and convert it.

[ksuess]

Also if you think that this is a common thing that would improve rst-to-myst, I would encourage you to submit a pull request to the project. The maintainers are very responsive and helpful.

The tweak affects Python files, so it's not a bug and it's not a bug in rst-to-myst converter. I added docstrings for a better understanding if this after-conversion-script https://github.com/plone/plone.api/blob/96e11c0550d092d5022e0f6402251aaf764d7176/fix-converted-myst.py is needed in other packages.