docs: add Sphinx documentation following Diataxis framework#332
docs: add Sphinx documentation following Diataxis framework#332
Conversation
gforcada
left a comment
gforcada
left a comment
There was a problem hiding this comment.
Wow, nice job!! 🌟
Breaking the gigantic REAME.md monolith into these nice diaxataris (I will never learn how to write it properly 😆 ) documentation is simply amazing and beautiful, thanks Jens!! ❤️ 💯
Though, as it was AI generated, there are quite a few changes that need to be made. I did expect more mistakes, but it got it quite well I have to say 👍🏾 So, here is the slew of non-AI generated comments on the files 🤓
UPGRADE.md got forgotten, and it is important to add it here.
| - `-t, --type`: define the configuration type. | ||
| At this time, `default` is the only option. | ||
| This option is only needed one time as their values are stored in `.meta.toml`. | ||
| Full documentation is available at **https://plone.github.io/meta/** |
There was a problem hiding this comment.
That's what GitHub provides by default, do we want to eventually put that under docs.plone.org? 🤔
There was a problem hiding this comment.
we could put the whole thing there. As said I generated it for me to get a better understanding and was about to delete it and then told myself it might be general useful, so lets create an PR without thinking further. maybe @stevepiercy has an opinion here too?
There was a problem hiding this comment.
It's helpful to use RTD for pull request previews, which is what the cookieplone documentation template helps do.
We should use plone-sphinx-theme for these docs. That's my only blocking requirement for this PR.
All official Plone documentation should be hosted under the plone.org domain or one of its subdomains. There are still several outlying projects that need to be consolidated under docs.plone.org, and they appear not to belong to Plone, which makes us look scattered and disorganized.
We've already consolidated Volto, Plone REST API, and plone.api, and soon Diazo, into Plone Documentation. To do so, see Importing external docs with submodules.
However, I don't see these docs under docs.plone.org for quite some time.
I won't have time to do a detailed review of this PR to make sure it complies with Plone 6 Documentation style for at least another month, probably two or more. I'm backlogged with Plone Documentation as it is, plus $WORK. I won't block merging this PR, but I can't approve it either. When I did a cursory check, there's a lot of room for improvement. AI tends to throw together sloppy markup that is not semantic, repetitive narrative language, or is a vague "word salad". If these docs eventually make it under docs.plone.org, then they'll need to be made compliant at that time.
There was a problem hiding this comment.
Then let's keep it under plone.github.io until we have time to make them good enough to land on docs.plone.org 👍🏾
Still, let's get it merged so we can keep improving them as we go.
If you have tips for how to make them more semantic I would like to try to improve them in that direction 😄
|
Weaved in your comments! |
|
I think I addressed most of the concerns, also style wise. |
|
I will try to get this reviewed again within this week 🍀 I haven't forgotten 😅 |
Replace the monolithic README with comprehensive Sphinx documentation organized into the four Diataxis quadrants: Tutorials, How-To Guides, Reference, and Explanation. The README is reduced to a concise overview with links to the full docs. Includes a GitHub Actions workflow for deploying to GitHub Pages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add coverage for test matrix, shared GHA workflows/actions, constraints_files dict, custom_images dict, switch-to-pep420, modular tox templates, Python 3.14 support, and Debian Trixie. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add recursive-include rules for docs directory and exclude build artifacts (docs/.venv, docs/.mxmake, docs/html). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace shibuya with plone-sphinx-theme for consistent Plone branding. Remove custom layout template (OG meta handled by theme). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Gil Forcada Codinachs <gil.gnome@gmail.com>
- Add upgrade guide (UPGRADE.md) to Sphinx docs (major missing piece) - Fix factual errors: scope.md multi-version claim, false GitHub variables section, pyproject.toml merge claim, format env description - Reduce overly specific content that gets outdated (version lists, tool commands); add wildcard shorthand for test_matrix - Add context/disclaimers: template option discovery tips, GitHub-only notes as admonitions, --branch current highlighted - Tutorial: lead with uvx, remove bulk-updates tutorial, mark multi-call as experimental with zope.meta origin warning - Config: release=2.4, author=Plone Foundation, delete unused mx.ini - Reorder generated-files.md to group GitHub/GitLab sections Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add description, og:description, og:title, and keywords metadata to all 24 documentation pages per Plone documentation standards. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace plain backtick file references with MyST {file} role
per Plone documentation standards. Covers .meta.toml, template
files, generated config files, and directory paths across all pages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove AI-style filler phrases ("In this tutorial you will...",
"By the end, you will understand...", "This guide shows...")
- Replace "the user" with "you" (Plone docs style)
- Use imperative mood for instructions
- Shorten verbose sentences throughout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Per Plone documentation standards, each sentence gets its own line for cleaner diffs in pull requests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Join lines where a single sentence was broken across multiple lines. Per Plone style, each sentence should be exactly one line for clean diffs. Also fix code blocks in write-custom-templates.md that were incorrectly joined, and restore admonition formatting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
gforcada
force-pushed
the
docs/add-sphinx-diataxis-documentation
branch
from
cb24f0b to
cc10ee3
Compare
There is indeed a `.github/workflows/test.yml` but that is only for Plone 6.0, so hardly useful for anyone right now.
|
With all remarks from @stevepiercy let's still merge it and create a ticket to get them in a better shape so they can be included to docs.plone.org |
3 participants
Summary
constraints_files,custom_images,switch-to-pep420, modular tox templates, Python 3.14 supportDocumentation structure
.meta.toml, configure GitHub Actions, configure GitLab CI, re-enable actions, custom branches, write custom templates.meta.tomloptions, generated files, tox environments, shared workflows & actions, changelogDocs infrastructure
llms.txtfor LLM-friendly project summaryTest plan
make docsbuilds successfully with zero warnings (25 source files)🤖 Generated with Claude Code
I generated this in order to get a better understanding of plone meta. I hope this is accepted, the content looks good to me, that said I am not a meta expert.