plone.meta distribution

[gforcada]

Closes #239

Finally, I had some time to breath and decided to bite the bullet: plone.meta is born 🎉

I'm by all means not a lawyer, and I can't remember what we decided regarding the license, I will check it up and update, but if anyone remembers, or has more knowledge about it, please share it 👍🏾

[gforcada]

@stevepiercy we have a huge config/README.md that with this change it has 2 problems:

• it should probably be published somewhere, as it will be a proper python distribution
• it will be partially outdated and adding a bit of structure might be nicer/easier for others to read

For the publishing part an easy short cut would be to, yet again, copy what zopefoundation/meta repository is doing: publishing the docs on readthedocs. I can copy/adapt their configuration and wish for the best 🤞🏾 otherwise advice on what to do would be great 🙇🏾

For the structure part I'm all open to suggestions and would be glad to get some advice. I will try my best to bend and twist the current documentation to the new proposed structure.

[stevepiercy]

For a good best practice repo, check out https://github.com/plone/plone-sphinx-theme. I plan to use it for a Plone docs distribution.

I'll be offline for a couple days, but will check back later.

[stevepiercy]

Only a minor grammar thing for the moment. Otherwise LGTM.

[stevepiercy]

@gforcada I put together a PR for Plone 6 Documentation. It's a how-to guide.

• Add Standardize Python project configuration developer guide documentation#1830

We've adopted the Diátaxis Framework for structuring docs, and we're slowly moving toward it, instead of having a mixture of all the quadrants in a page.

[mauritsvanrees]

This looks good. Thanks!

I have committed a few fixes, please check.

I think the only thing left is documentation. The config/README.md could be merged into the main README, making the config directory completely empty. It needs some updates because the installation is different. You don't call python config-package.py, but ./venv/bin/config-package.

Or we do that in plone/documentation#1830, and let the plone/meta/README.md point to the new guide.

[stevepiercy]

think the only thing left is documentation. The config/README.md could be merged into the main README, making the config directory completely empty.

I agree.

I also want to reorganize sections, putting how-to stuff first (install, usage, then configuration, as that's a common workflow), and move the explanation stuff last (philosophy).

It needs some updates because the installation is different. You don't call python config-package.py, but ./venv/bin/config-package.

It was renamed to config_package.py, so should that command change, too?

Or we do that in plone/documentation#1830, and let the plone/meta/README.md point to the new guide.

My original thought was to make Plone Documentation of plone/meta be minimalist and refer to the README. The current README confused this simple-minded first-timer, and writing that pull request was designed to reduce confusion from the next first-timer. That idea would also give plone/meta more exposure. However we could reverse that idea, and move all the docs from the README into Plone Documentation and link to that. I'm fine with either option.

[stevepiercy]

Minor grammar fix.

[stevepiercy]

AFAICT, the only thing keeping this PR from being merged is a decision on the direction of docs. I'd like to work on the docs and wrap this up, but not without a decision for their direction. I don't want to spend time on things that aren't wanted.

The options are:

1. Do nothing further and close Add Standardize Python project configuration developer guide documentation#1830.
2. Merge contents of the readmes into the root.
3. Move content of the readmes to Add Standardize Python project configuration developer guide documentation#1830, and have a single readme at the root that has a link to the docs.

@gforcada @mauritsvanrees @davisagli @ericof and anyone else who cares, what is your decision?

[mauritsvanrees]

I would say number 2, merge contents of the readmes into the root. Main reason: if you add a new option to plone.meta, you can do that in one PR, instead of having to do a separate PR for the documentation.

A guide in the docs is still good. It makes people aware that there is such a thing as plone/meta. That could contain just basic installation and usage instructions. So roughly what the current docs PR does. And then point at the plone/meta repo for details.

BTW, once the current plone/meta PR is merged, I think we should add this repo to buildout.coredev in the sources, always have it checked out just like the docs, and add a buildout part like this so the commands are available:

[meta]
recipe = zc.recipe.egg
eggs =
    plone.meta

@gforcada Does all this make sense to you?