Purge empty pages and todos

Open stevepiercy opened this issue 10 months ago • 11 comments

We've had empty pages and TODOs for over three years in Plone 6 Documentation, especially under the Backend section, but also under Deployment, Classic UI, Volto, and Contributing. The Plone 6.1 milestone has only 17% of its issues completed after the release of Plone 6.1. The lack of current and accurate documentation for Plone 6 is the single greatest barrier to entry for all audiences. This reflects extremely poorly upon Plone, where documentation is perceived as less than an afterthought.

The following list of URLs are affected.

Purge empty pages. A page is empty when either it has no content or its only content is a TODO. If there is no existing issue for the page, then create a new issue.

All other pages in the list have content with at least one TODO. For these pages, preserve the TODO. If the TODO does not contain a link to an existing issue, then create a new issue and add its URL to the TODO, except for obsolete TODOs, such as Upgrading Plone 4.x to 5.0.

Configure conf.py to hide the display of TODOs, changing code from the following...

https://github.com/plone/documentation/blob/b4462a84bac18a56ea8a37390cd87b027e8b85bd/docs/conf.py#L381-L385

...to the following.

# -- Options for sphinx.ext.todo -----------------------

# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
todo_include_todos = False
todo_emit_warnings = True
todo_link_only = True

Ref: https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration

[ ] https://6.docs.plone.org/backend/annotations.html
[ ] https://6.docs.plone.org/backend/behaviors.html#built-in-behaviors below the table. TODO: Linked issue is complete.
[ ] https://6.docs.plone.org/backend/configuration-registry.html
[ ] https://6.docs.plone.org/backend/control-panels.html - https://github.com/plone/documentation/pull/1909
[ ] https://6.docs.plone.org/backend/portal-actions.html#expressions TODO
[ ] https://6.docs.plone.org/backend/search.html TODO and empty headings
[ ] https://6.docs.plone.org/backend/security.html
[ ] https://6.docs.plone.org/backend/sending-email.html
[x] https://6.docs.plone.org/backend/subscribers.html - https://github.com/plone/documentation/pull/1918
[ ] https://6.docs.plone.org/backend/traversal-acquisition.html
[x] https://6.docs.plone.org/backend/upgrading/preparations.html#back-up-your-plone-site TODO - https://github.com/plone/documentation/pull/1919
[ ] https://6.docs.plone.org/backend/upgrading/troubleshooting.html TODO
[ ] https://6.docs.plone.org/backend/upgrading/version-specific-migration/p4x-to-p5x-upgrade.html TODO
[ ] https://6.docs.plone.org/backend/users-groups.html
[ ] https://6.docs.plone.org/backend/vocabularies.html
[ ] https://6.docs.plone.org/backend/workflows.html
[x] https://6.docs.plone.org/backend/zodb.html - https://github.com/plone/documentation/pull/1894/
[ ] https://6.docs.plone.org/classic-ui/forms.html multiple TODOs
[ ] https://6.docs.plone.org/classic-ui/templates.html
[ ] https://6.docs.plone.org/classic-ui/viewlets.html multiple TODOs
[ ] https://6.docs.plone.org/classic-ui/views.html multiple TODOs
[ ] https://6.docs.plone.org/conceptual-guides/components.html TODO
[ ] https://6.docs.plone.org/conceptual-guides/package-management.html#manage-frontend-node-js-packages TODO
[ ] https://6.docs.plone.org/contributing/core/plip-review.html#javascript TODO
[ ] https://6.docs.plone.org/contributing/documentation/themes-and-extensions.html and purge the extension from conf.py and possible PST.
[ ] https://6.docs.plone.org/deployment/caching/rulesets-and-caching-operations.html#no-caching-plone-app-caching-nocaching TODO
[ ] https://6.docs.plone.org/deployment/continuous-integration-and-deployment.html
[ ] https://6.docs.plone.org/deployment/index.html TODO
[ ] https://6.docs.plone.org/deployment/optimize-and-tune.html
[ ] https://6.docs.plone.org/deployment/orchestration.html
[ ] https://6.docs.plone.org/i18n-l10n/language-negotiation.html TODOs should be a warning.
[ ] https://6.docs.plone.org/i18n-l10n/translating-content.html#language-selector TODO
[ ] https://6.docs.plone.org/i18n-l10n/translating-text-strings.html TODO should be a warning.
[ ] https://6.docs.plone.org/plone.restapi/docs/source/usage/content.html multiple TODOs
[ ] https://6.docs.plone.org/volto/client/actions/database.html
[ ] https://6.docs.plone.org/volto/conceptual-guides/index.html add toctree
[ ] https://6.docs.plone.org/volto/contributing/react.html
[ ] https://6.docs.plone.org/volto/contributing/routing.html
[ ] https://6.docs.plone.org/volto/user-manual/blocks.html multiple TODOs
[ ] https://6.docs.plone.org/volto/user-manual/index.html

@plone/volto-team @plone/restapi-team @plone/ci-team @plone/classicui-team @plone/marketing-communications @plone/documentation-team @plone/developers

Mar 02 '25 23:03 stevepiercy