search

plone / volto

React-based frontend for the Plone Content Management System
https://demo.plone.org/
MIT License
426 stars 576 forks source link

Plone 6 docs #3001

Closed tiberiuichim closed 2 years ago

tiberiuichim commented 2 years ago

Integration with the sphinx build for plone documentation, at this branch. https://github.com/plone/documentation/tree/6-dev

I've kept the changes minimal. We can adjust and optimize, along the way.

I've added some index files, I think they're needed for sphinx. The ways shinx does the navigation is a bit of a mystery to me, in any case, they're new files, no linked from the mkdocs configuration.

See also related PR at https://github.com/plone/documentation/pull/1160/files

sneridagh commented 2 years ago

@tiberiuichim

Should we change from mkdocs to a MyST build in Volto as well? What do you think? I'd say so, to maintain coherence before all is settled. During the transition, it would be to maintain docs.voltocms.com up and running using the MyST build.

tiberiuichim commented 2 years ago

I've noticed that I've executed the "update md files with headers" script from the plone/documentation branch and it updated all .md files in Volto. I'll need to reset them, we don't want them changed.

stevepiercy commented 2 years ago

How do you want to manage branches in the long term? I assume that eventually we would want to pull from volto/master into documentation/6-dev (and eventually documentation/6.0 for release).

How about this process?

  1. Create, finalize, and document process to pull volto docs into Plone docs, including how to contribute to volto docs and have those changes reflected back into Plone docs.
  2. Convert to MyST and clean up bugs. Do not add new stuff yet.
  3. addMetaData.py to add blank meta headers for improved SEO. Add content to the blank headers.
  4. Any other updates.

I don't know how y'all would want to manage this, but I would think that at the completion of each step, merge this branch to master and cut a release of the docs, then reopen this branch with the next step. Thus we do not need to change the branch in the submodule until it is ready for final release. What do y'all think?

tiberiuichim commented 2 years ago

Thus we do not need to change the branch in the submodule until it is ready for final release. What do y'all think?

Ok with me.

nileshgulia1 commented 2 years ago

+1 from me. My just 2 cents, we can keep a common documentation for Volto either in Plone/documentation or docs.voltocms, or link to the current one from Plone 6 docs.

stevepiercy commented 2 years ago

What are the next steps for this PR? Please add to the task list:

EDIT See https://github.com/plone/volto/pull/3001#pullrequestreview-885164648

stevepiercy commented 2 years ago

@sneridagh is this PR really ready to merge to master, per your approval?

For stand-alone Volto docs, is it correct that we want to switch from MkDocs to MyST/Sphinx, then when we are happy with the stand-alone build, replace the MkDocs version with the MyST/Sphinx version?

If so, we should make sure that this branch can build and deploy successfully to wherever the docs are hosted, using MyST and Sphinx as the platform.

sneridagh commented 2 years ago

@stevepiercy

Add MyST and Sphinx configuration from plone/documentation@6-dev

We can do it later, let me test if it still builds in mkdocs. However, we could start redirecting to the new domain asap.

Fix all but 2 broken links and redirects #3019

Commented in there. Sorry, busy day, if not I'd do it myself.

Update doc tests, if any

Nope.

Update CI/CD to build docs

Don't think we need any now.

Do we migrate storybook and include it in the Plone 6 Documentation under docs/volto/storybook/?

good one, we can ask @ericof for it.

The rest LGTM, let's merge it.

Then the documentation PR should point to master then, right?

sneridagh commented 2 years ago

@stevepiercy Fred has been working in some optimisations in #3010 . Let's merge that one first, then solve merging conflicts (they look ok). Then this one, ok?

stevepiercy commented 2 years ago

@sneridagh agreed. Let's see your results of mkdocs build. I expect the changes I made to some links will fail, because I converted them from Markdown to MyST/Sphinx syntax. There might be other issues that come up.

sneridagh commented 2 years ago

All good in my build... No worries for the links change, either we point to the new docs asap or we update the build with Sphinx/MyST.

sneridagh commented 2 years ago

I've talked to Steve, we will wait until this is done and we have the MyST build in place.

So, he will merge the documentation PR, pointing to this PR for now.

stevepiercy commented 2 years ago

I caught a few issues that resulted from merging master into plone6-docs, fixed them, and pushed those commits. We're back into a good clean state on this PR.

From this point forward, please use pull requests to the branch plone6-docs to update it. This will allow peer review of work.

sneridagh commented 2 years ago

@stevepiercy I've been talking to @tiberiuichim and we both agreed that it would be best to resolve and merge the docs as soon as possible since this "in between, let's backport all the changes" state is cumbersome. Since we don't really have a strong reason for not to merge it as soon as possible I'd try to move forward quickly on this one. I'm totally ok with having the Volto docs in https://6-dev-docs.plone.org and a redirect in docs.voltocms.com right away.

So, what is missing now?

/cc @tiberiuichim @ericof @tisto

tiberiuichim commented 2 years ago

If we can setup a "smarter" redirect on docs.voltocms.com/(.*) -> https://6-dev-docs.plone.org/volto/$1, sure

stevepiercy commented 2 years ago

Just to confirm, it sounds like we do not need to update any CI/CD for deploying Volto docs, as we will be using Plone 6 Docs for that.

The only thing that you might want to add is something to automatically preview a PR or branch, like we do on Netlify for Plone 6 Docs. If that is needed, we can create an issue to track it. We have an Open Source License with Netlify, and I can add y'all to the team.

However we do need to update CI/CD for testing the docs. See https://github.com/plone/volto/pull/3070#issuecomment-1042375884

stevepiercy commented 2 years ago

One more todo, after merge to master, we need to update the Plone 6 Docs instructions and Makefile to use the master branch instead of plone6-docs, and update the git submodule. I will prepare a PR for that eventuality.

netlify[bot] commented 2 years ago

✔️ Deploy Preview for volto ready!

🔨 Explore the source changes: 25ebced9b03738167b8cae6ae0683423788faa7d

🔍 Inspect the deploy log: https://app.netlify.com/sites/volto/deploys/6212302832886900072a6017

😎 Browse the preview: https://deploy-preview-3001--volto.netlify.app

sneridagh commented 2 years ago

@stevepiercy status right now:

These changes must wait. We have several prerequisites that need work before we can enable Sphinx and MyST on the master branch:

Let's do this!

stevepiercy commented 2 years ago

I thought about this one some more. I am OK with removing this as a requirement to merge this PR. There are 211 of these errors currently, and it takes time to create useful meta tags. I would much prefer to have quality SEO than hastily thrown together garbage. Instead whenever we update a page, let's make it a practice to update the html_meta values at the top of the page.

stevepiercy commented 2 years ago

@sneridagh the final remaining requirements have been resolved. This PR can be merged at anytime. Please do the honors at your convenience.

stevepiercy commented 2 years ago

Oops, not so fast. We have two open PRs against this branch:

sneridagh commented 2 years ago

@stevepiercy 😱 with pleasure! There are also some actions to do in the documentation repo afterwards, right?

stevepiercy commented 2 years ago

Correct. https://github.com/plone/documentation/pull/1182 is waiting to merge.

We also need to update the submodule pointer.

sneridagh commented 2 years ago

@stevepiercy merged backport, waiting for green on docs.

sneridagh commented 2 years ago

@stevepiercy also merged https://github.com/plone/documentation/pull/1182 and updated the tip of the submodule in documentation repo.

sneridagh commented 2 years ago

Mmmm Mr.Roboto thinks that the docs repo should be included in the checkouts of coredev?

/cc @mauritsvanrees @jensens @fredvd @gforcada

stevepiercy commented 2 years ago

Thanks for merging both PRs.

Regarding coredev, see https://github.com/plone/buildout.coredev/issues/768