Documentation - add clarity on how to correctly customise edit_handler (publish/comments)

[lb-]

Pertinent section of the Wagtail docs

https://docs.wagtail.org/en/latest/advanced_topics/customisation/page_editing_interface.html#customising-the-tabbed-interface

Details

Due to the removal of using SettingsPanel in the default set of panels for page editing there is now a bit of a documentation gap in whether this panel is needed with custom edit_handler behaviour.

To ensure that the editing interface can be used for publishing and commenting the CommentPanel and the PublishPanel are now required OR the SettingsPanel must be included (but this will now be an empty panel).

Ideally this nuance should be clarified in the section linked above. Maybe with an example of both ways of doing things.

Additional context

I've just done a quick test with Wagtail 4.2 and a minimal extension to the HomePage installed from the startup guide. I can confirm @laymonage's comments above, that either the Page.settings_panel, or the CommentPanel and PublishingPanel in another panel, are required in the Page edit_handler to get the commenting and full publishing capability.

Now that the Settings tab has vanished, a developer customising the edit_handler and following the new instructions will end up omitting both of the above, and hence lose the commenting and publishing panel functionality. I can understand @laymonage's description that these panels have to be in the edit_handler somewhere, but should this detail be exposed to the developer, or another mechanism found to slip these panels in?
Once decided, the documentation can be adjusted accordingly, but I believe this particular change doesn't accurately describe the behaviour in 4.2.
Originally posted by @dkirkham in #9813 (comment)

[lb-]

@dkirkham / @laymonage - I have split out the discussion to a new issue from #9813 - feel free to add any additional context or suggestions.

I'll flag this as 5.0 as it may be good to resolve this and even backport the docs to 4.2 branch as it does seem like this could cause confusion in the docs on main now and also the docs in 4.2. branch.

[dkirkham]

Thanks @lb-,

I've loaded up my test code as a gist, for reference. To use, start a fresh Wagtail project (as per the Getting Started guide), replace home/models.py with the gist, do the migrations and runserver. There are a couple of lines hashed out which allows a few scenarios to be tried easily.

[lb-]

It's possible that this PR #11614 has resolved this issue.

[dkirkham]

I think it has, although the second example doesn't have the Promote panel. I would have thought that would be desirable, but maybe it isn't necessary.

[gasman]

I think it has, although the second example doesn't have the Promote panel. I would have thought that would be desirable, but maybe it isn't necessary.

Agreed it can't hurt to add that... Added in #11893.

[gasman]

Completed in #11614 and #11893