Convert appearance-related modules: breakpoint, color, layout_builder, layout_discovery module hook_help() to topic(s)

Tested patch, found error with patch when trying to view admin/help page.
Fixed error, patch is good.

I got an error after applying your patch

The website encountered an unexpected error. Please try again later.

Drupal\Component\Discovery\DiscoveryException: /var/www/docroot/core/modules/color/help_topics/color.overview.html.twig contains invalid meta tag with name='lable' in Drupal\help_topics\HelpTopicDiscovery->findAll() (line 134 of core/modules/help_topics/src/HelpTopicDiscovery.php).

We need to postpone this until the #2920309: Add experimental module for Help Topics gets committed. No idea when/if that might happen right now...

That issue was committed, so we can un-postpone this now!

Adding some more theme-related modules to this issue. None of them had patches yet.

Needs more added to the patch.

Fixed fatal error due to typo. Also capitalised the label to match the label of others.

Attached now covers breakpoint, color, layout_builder, layout_discovery, field_layout. Updated labels to match other core help topic labels to be descriptive of the action rather than just the module label.

We'll need a follow-up to this to have 'breakpoint' eventually use related help topics for field and field UI modules instead of referring to the module help pages I think.

Converting incorrect heading hierarchy to correctly start with h2 (and upping lower levels to match) so this will pass the h1-h6 proper hierarchy test being worked on here https://www.drupal.org/project/drupal/issues/3037228#comment-13173104

1. Patch applied via STM
2. The experimental Help Topics module was enabled (Added screenshot below)
3. Reviewed each topic that was created and modified in this patch. Reviewed the patch for spelling and grammar. The topics are files in the patch ending in .html.twig. URLs work as well. (Added screenshot below with each topic)
4. Verified that all the tasks described in the overviews are covered in the topics.

Only thing I would change is Color help-topic. I added screen with original hook_help0 (Color) and help-topic (Changing your site's colour scheme). "About" was changed to "What is color?" and "Uses" to "How to use?", that I think it wasn't necessary.

Actually, the heading changes are a good idea. From the issue summary on this issue:

We want to end up with one or more topics about the tasks that you can do with this module. So, read the help and figure out a good way to logically divide it up into tasks. Each task will need to be in its own topic.
...
Do not just copy the text of the old module overview word-for-word. We don't want an overview of the module -- we want one or more topics that are task-centered, that would be useful for someone managing or building a Drupal site. If you need to explain a concept, put that in a separate section or sections within the related task topic, with headers like "What is/are...?" question, such as "What are actions?".
...
Also verify that it is task-based help, and that concepts that need to be explained are in separate sections with "What is/are" questions as headers (such as "What is an action?").

We are working on some other standards on other issues right now, but probably we want the task sections to have headers using -ing verbs (like we have in the User Guide). Such as "Changing the colors on your site" not "How to change colors".

Updated issue summary with better instructions/guidelines

Another iteration on guidelines. Please read the new issue summary. The existing patch is a good start, but it doesn't follow the new guidelines and instructions, which set out what we're really looking for in these patches. Thanks!

Thanks for the feedback! I have updated the 'color' help topic. Before I do the others, I just wanted to check if I am on the right track.

1. Patch applied via STM
2. The experimental Help Topics module was enabled.
3. Reviewed the patch for spelling and grammar. I found few things, that needs to be fixed in "Changing your site's color scheme". I showed it in screenshot.
- The topics are files in the patch ending in .html.twig. URLs work as well.
4. "Managing your site's color scheme" topic has "online documentation for the Color module", that needs to be under "Additional resources" (see Standards for Help Topics https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...)

Let's see maybe I skipped something.
@jhodgdon do you want to add something?

We've migrated the help topic standards to https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... so updating issue summary again.

Thanks for the patch and review!

My suggestions about the topics:
- I actually think that we don't need a separate overview and task topic for the Color module. In the current standards, we allow "What is" headings in a task topic, and we say if you only have one task to document, then you should just have one topic and put the background information in there.
- Maybe if the "What is" heading was something like "What is a colorizable theme?", that would be the place to explain that some themes are compatible with the core Color module, which lets you set colors for various aspects of the theme in the administrative user interface. And then maybe "How are the colors saved?" [even though that doesn't start with "What", it is background information] -- where you could talk about the files that are created, where they are saved, and when you need to update them. Then you could get rid of the "common issues" section, because it would already be covered in the background information.
- Maybe the topic could be called "Changing the colors of a theme". Probably it doesn't need to be top-level -- I was thinking that all of these topics might be grouped together under a top-level topic that could be called something like "Configuring the appearance of your site" or something like that.

Tagging this for badcamp2019. (October 2-5)

We just found out that all topic Twig files currently need to go into core/modules/help_topics/help_topics (with their finalized module-based file names), for the time being until the Help Topics module is stable. Updating issue summary. Patch will need to be updated too.

I re-created patch as per new help topic standers #21 need to work.

This patch still has several topics with an "About" and "Uses" headings. Please fix that -- we don't want a copy/paste of the hook_help text.

Over on #3041926: Convert automated_cron, ban, dblog, syslog, system, update, and user module hook_help() to topic(s)... That patch was getting pretty big, so I would like this issue to cover installing/uninstalling/configuring themes as well as the other topics already listed.

Please take a look at the help topic standards. There are two types of topics, tasks and overviews, and they have different headings. These topics are not following the standards. https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...

@jhodgdon
I was able to figure out only one issue which is as given below:
- Goals mentioned under breakpoint.overview.html.twig. should be changed to Goal
-
Can you elaborate if you find something which is pretty evident and I am failing to notice.?

Here are some thoughts about the topics:

a) field_layout.overview.html.twig has heading "About"

b) layout_discovery.overview.html.twig also has heading "About".

c) Both of those topics (and perhaps some of the others, I didn't look carefully) seem to be copy/paste of the content from the hook_help for those modules. Please read the instructions in the issue summary about how to divide things into topics. We really *do not want* topics that are overviews of what a specific module does. We do want topics that explain concepts (like maybe "What is a layout?"), and that give steps for tasks (like maybe "Setting up a page layout") (I made both of these things up, I'm not sure if those are good concepts/tasks for these modules, as I don't know much about them).

d) Please verify that the links in Additional Info sections actually take you to useful information. In the old hook_help we always linked to the online documentation, but if the online documentation has no useful info that is not in the topic, there is no reason to make that link.

Thanks @jhodgdon
Below are my observations and some doubts.
Changes observed
- Goals should be changed to Goal - breakpoint.overview.html.twig
- About should be changed to Goal - layout_discovery.overview.html.twig
- About should be changed to Goal - field_layout.overview.html.twig

Document used
https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...

Patch being reviewed:
https://www.drupal.org/files/issues/2019-11-20/3055055-30.patch

Breakpoint module being reviewed with the docuemntation

Title: A description of the task you can accomplish, starting with an -ing verb, such as "Setting permissions per role". This goes into the front-matter section ("label" element) at the top of the topic Twig file
--> DONE
Top-level: Every topic needs to either have the front-matter element saying it is "top_level" (top_level element), or needs to be Related to a top-level Section topic. Top-level topics are listed directly on admin/help.
—> DONE
Related topics (Optional): List topics related to this task, such as Section topics or related tasks. These are listed in the front-matter meta-data section ("related" element) at the top of the topic Twig file.
—> DONE, NOT REQUIRED for breakpoint
Goal: (should be an h2 heading called "Goal", at the top of the body section) In 1-3 sentences, describe the goal of the task, and possibly why you would want to do it
------> h2 heading called “Goal” -> Move it to top with “Goals” text changed to “Goal”
———> 1-3 sentences -> 2 DONE
——————> Describe the goal of the task
DONE
——————> Possibly why you would want to do it.

NOT DONE : Need to understand whether Uses comes under this ??

What is/are...: (optional) If there are terms that need to be defined, or background information that someone would need to know to accomplish the task, you can add one or more sections, under h2 headings starting with "What is/are...". However, if there are multiple tasks related to this background information, put this information into a Section topic instead.

————>We have multiple tasks like Breakpoint, Media Query, Resolution Multiplier and Breakpoint Group.
Is it proper to call them task?
Older version of help description had it as terminology
What is a Section Topic ?

Steps: (h2 heading) The steps needed to accomplish this task. Usually should contain a numbered list of actions to take.

————> We have steps mentioned in the online docs: https://www.drupal.org/docs/8/theming-drupal-8/working-with-breakpoints-...

————> So can we SKIP STEPS for the breakpoint , is that correct approach ?? Or we need to study breakpoint module add basic actions to be taken ?

Additional resources: (optional h2 heading) One or more links to outside material (documentation on drupal.org, videos, etc.)
that expands on this topic. The preferred place to link would be a page inside of the User Guide. Make sure all links have link
text showing the name of the item being linked to. Only include materials directly relevant to this topic,
and only if there is not another Help Topic that covers the information (in which case the link would instead go in the Related topic meta-data).

———> DONE Seems to be correct.

Parts of a section topic
Here are the parts of a Section topic:
1. Title (as in a Task topic). Typically it would be something like "Managing blocks" for a Section topic.
2. Related and top-level (optional, as in Task topic). Section topics must be top-level, so that we don't end up with a large hierarchy of topics.
3. What is/are...: (optional, as in Task topic)
4. ... overview: (h2 heading, such as "Managing blocks overview") 1-3 sentences describing the tasks related to this section, ending with this sentence: "See the related topics listed below for specific tasks."
5. Additional resources: (optional, as in Task topic)

-----> Don’t see any example of Section Topic in the existing help_topics in core module help_topics ?

General Standards
* All text in the body of topics needs to be wrapped in {% trans %} ... {% endtrans %} so that it can be translated.

——> TESTED
* When describing navigation (usually as part of the Steps in a task topic), use a format like: "In the Manage administrative menu, navigate to Structure > Content types." If it is possible, make the last part of the navigation into a link to the page that you would end up on (this is not always possible; for example, if you are telling someone to select a particular content type as part of the navigation, or if the page belongs to a different module than the one that is being documented).

——> No steps noted for Breakpoints ,no use case found

* Help topics should be written in complete sentences.
——> TESTED

* Be as direct as possible: so tasks should be written in imperative mood ("Do this." not "You could do this.")

——> TESTED , no use case found in breakpoints

* Avoid words like "please" and "simple" and "obvious".
——> Tested
* Follow the UI text standards at https://www.drupal.org/node/604342 and https://www.drupal.org/drupalorg/style-guide/content

—> NOT Tested

* In general, link to other help topics rather than duplicating information that is in other help topics. For example, in a topic that is about configuring the Search module, if one of the steps is placing a block, just say to place the block and link to the block placing topic (don't explain all the steps needed to place a block).

——> No Use case noted for breakpoints

* There are two ways to link to a help topic:
* (a) put it in the Related Topics section (see details below),
* or
* (b) within the text, make a link to the topic. As a note, the URL of a topic can be put into a Twig variable like this:

---- looks correct.

Once its clear for breakpoint, it should be easier for other modules(help topics).

Hi @jhodgdon

+++ b/core/modules/help_topics/help_topics/color.changing_colours.html.twig
@@ -0,0 +1,18 @@
+---
+label: 'Changing your site color scheme'
+related:
+  - color.overview
+---
+{% set appearance = render_var(url('system.themes_page')) %}
+<h2>{% trans %}Goal{% endtrans %}</h2>
+<p>{% trans %}Change the color scheme scheme of your site such as the color of links, backgrounds, or text.{% endtrans %}</h2>
+<h2>{% trans %}Steps{% endtrans %}</h2>
+<ol>
+  <li>{% trans %}Navigate to the <a href="{{ appearance }}">Appearance</a> configuration page.{% endtrans %}</li>
+  <li>{% trans %}Select the <em>Settings</em> link for the theme you want to change the colors for.{% endtrans %}</li>
+  <li>{% trans %}Choose the new colors as desired.{% endtrans %}</li>
+  <li>{% trans %}Save the settings{% endtrans %}</li>
+</ol>
+<h2>{% trans %}Common issues{% endtrans %}</h2>
+<p>{% trans %}If the color picker does not appear then the theme is not compatible with the Color module.{% endtrans %}</p>
+<p>{% trans %}The Color module saves a modified copy of the theme's specified stylesheets in the files directory. If you make any manual changes to your theme's stylesheet, <em>you must save your color settings again, even if you haven't changed the colors</em>. This step is required because the module stylesheets in the files directory need to be recreated to reflect your changes.{% endtrans %}</p>

What do you call Common Issues with h2 tag , is it a task topic or section topic ?
What is the proper place to have it under?
Also for color.overview as given in code snippet given below

+++ b/core/modules/help_topics/help_topics/color.overview.html.twig
@@ -0,0 +1,10 @@
+---
+label: 'Managing your site color scheme'
+top_level: true
+---
+<h2>{% trans %}What is color?{% endtrans %}</h2>
+<p>{% trans %}The Color module allows users with the <em>Administer site configuration</em> permission to quickly and easily change the color scheme of themes that have been built to be compatible with it. In order for the color module to work, a theme must be specifically designed to use the color changing features.{% endtrans %}</p>
+<h2>{% trans %}Additional resources{% endtrans %}</h2>
+<ul>
+  <li><a href="https://www.drupal.org/documentation/modules/color">{% trans %}Online Documentation for  Color module{% endtrans %}</a></li>
+</ul>

I see What is color ? which should probably be Goal Do you agree ?
—> the initial color module description in additional resources matches with that in the Help Topics so what should be done ?

The Color module allows users with the Administer site configuration permission to quickly and easily change the color scheme of themes that have been built to be compatible with it.
In order for the color module to work, a theme must be specifically designed to use the color changing features.

The initial color module description in additional resources link matches with that in the Help Topics so what should be done ?
Should it be a custom help text or we can discard it and just add additional resources link ?

Also, Where should the use cases be listed in the help topics ?

+++ b/core/modules/help_topics/help_topics/layout_builder.overview.html.twig
@@ -0,0 +1,20 @@
+---
+label: 'Layout Builder'
+top_level: true
+related:
+ - layout_discovery.overview
+---
+<h2>{% trans %}What is layout builder?{% endtrans %}</h2>
+{% set field_help_url = path('help.page', { 'name': 'field' }) %}
+<p>{% trans %}Drupal's Layout Builder offers a single, powerful visual design tool for the following three use cases:{% endtrans %}</p>
+<ol>
+  <li>{% trans %}<em>Layouts for templated content.</em> The creation of "layout templates" that will be used to layout all instances of a specific content type (e.g. blog posts, product pages).{% endtrans %}</li>
+  <li>{% trans %}<em>Customizations to templated layouts</em> The ability to override these layout templates on a case-by-case basis (e.g. the ability to override the layout of a standardized product page).{% endtrans %}</li>
+  <li>{% trans %}<em>Custom pages.</em> The creation of custom, one-off landing pages not tied to structured content (e.g. a single "About us" page).{% endtrans %}</li>
+</ol>
+<p>{% trans %}The Layout Builder provides the ability to drag and drop site-wide blocks and content fields into regions within a given layout. Additionally, custom "inline" blocks can be created for one-off details specific to a given layout.{% endtrans %}</p>
+<p>{% trans %}Note that Layout Builder is not turned on by default in Drupal.{% endtrans %}</p>
+<h2>{% trans %}Additional resources{% endtrans %}</h2>
+<ul>
+  <li><a href="https://www.drupal.org/docs/8/core/modules/layout-builder">{% trans %}Online Documentation for Layout Builder module{% endtrans %}</a></li>
+</ul>

So ordered list added above ,
what should be the ideal place for it to be added ?

For layout_discovery.overview.html.twig

Should I write Steps on how to register/discover layouts for modules or themes ? as a part of Task Topic ?

1. Created three section topics for breakpoints (breakpoint.overview.html.twig)

• Resolution Multiplier (breakpoint.resolution_multiplier.html.twig)
• Media Query(breakpoint.media_query.html.twig)
• Breakpoint Group (breakpoint.group.html.twig)

2. Updated labels(Title) for Layout Builder (layout_builder.overview.html.twig) & Layout Discovery (layout_discovery.overview.html.twig)

3. Changed Heading for layout_discovery.overview.html.twig, layout_builder.overview.html.twig and field_layout.overview.html.twig

hi @hash6,

Reviewed the patch and check spelling and grammar.

1. Add below point in ayout_builder.overview.html.twig

Default layouts
Layout Builder can be selectively enabled on the "Manage Display" page in the Field UI. This allows you to control the output of each type of display individually. For example, a "Basic page" might have view modes such as Full and Teaser, with each view mode having different layouts selected.
Overridden layouts
If enabled, each individual content item can have a custom layout. Once the layout for an individual content item is overridden, changes to the Default layout will no longer affect it. Overridden layouts may be reverted to return to matching and being synchronized to their Default layout.
User permissions
The Layout Builder module makes a number of permissions available, which can be set by role on the permissions page. For more information, see the Configuring Layout Builder permissions online documentation.

2. Check few grammatical mistakes in breakpoint.overview.html.twig

Thanks!

Also it looks like patch testing failed due to a YML parsing error:

Malformed YAML in help topic "/var/www/html/core/modules/help_topics/help_topics/breakpoint.resolution_multiplier.html.twig"
yaml_parse(): parsing error encountered during parsing:
did not find expected key (line 1, column 28), context while parsing a block mapping (line 1, column 1).

@jhodgdon Can you help with links on how I can perform tests locally
I am trying with the following command

   ./vendor/bin/phpunit -c web/core/phpunit.xml.dist  [name of file/directory]

Is that correct ?
-- sorry, ignore the above, I have figured it out.

Thanks @jhodgdon and @kishor_kolekar

I have updated the patch #38 with the following fixes.
- Fixed Failing tests.
- Fixed grammer on breakpoint.group.html.twig
- I see details for layout overview builder are not needed since we have added parent page link from drupal.org.

Thanks for the patches! I took a quick look at the latest one, just the Breakpoint section...

Please go read the help topic standards page again: https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...

There are very specific h2 headings required in Task topics and Section topics. The Overview topic should be a Section topic, but it has other headings in it that do not belong. Other topics that don't have goals and steps should be made into new sections of the Overview topic.

Once that is done, I will make more specific comments about the topics, but right now I would say the topics need to be reorganized. Thanks!

@jhodgdon Please have a look at it.

OK, going back to breakpoint.overview again: Again, please read the help topic standards. This is a Section topic. It is not following the standards for Section topics -- they have very specific headings. Not "Goal" and not "Uses". The other "What is" headings are what should be in an overview topic, plus one at the end -- just go read the standards page please.

@jhodgdon Thanks a lot for persistent help!!!,
I have removed Goal and Uses from the overview. I had one doubt though , that help_topics like contextual.overview.html.twig have Goal, is that because it's not a top level topic as can be seen as the difference between topics like block.overview.html.twig and breakpoint.overview.html.twig.
Let me know, Also check the updated patch and provide your feedback.

Please read the help topic standards page again.

There are 2 types of topics:
- Overview topics
- Task topics

Task topics describe 1 task, and have Goal and Steps. Overview topics have headings mostly like "What is...". This is all in the help topic standards page.

Please check your patch again when you have looked at this, and then I will take a look. Thanks!

@jhodgdon I have updated the other

overview topics
• color.overview.html.twig
• layout_discovery.overview.html.twig
• field_layout.overview.html.twig
• layout_builder.overview.html.twig

Removed Goals.

Please review it.
Thanks!!!

Thanks for the patch! I'm not sure when I'll have time to review this. If you would like to help, you could review this other patch (and I'll ask on that issue that they please review yours):
#3047719: Convert search module hook_help() to topic(s)

Hi @hash6
I applied your patch
#3047719: Convert search module hook_help() to topics as per @jhodgdon advised patch no #53 works properly LGTM RTBC +1.

Thanks!

I don't have time for a complete review, but I took a quick look, and I think this needs some English grammar/punctuation proofreading. For example, just near the top of the patch file I found:
"Breakpoints are the point a which your sites content" ==> should be site's content
"and other changes that need to respond to changes in viewport height or width" ==> awkward wording. Maybe "and other responses to changes in viewport ..."?
"What is Breakpoint Group" --> needs "a" in there.

That was just in the first few lines of the patch... I haven't looked at the rest but please proofread and also the next time someone reviews, please verify that all the topics are following the Help Topic Standards. Just because the patch applies doesn't mean it should be marked "reviewed and tested" unless you have given it a very careful review. Thanks!

As far as help topic standards go, there are problems like headings "Common issues" which is not an allowed heading. READ THE STANDARDS please. And follow them. Thanks!

Hy @hash6
The patch gets applied perfectly and I think all the topics are well covered. Thanks for the patch.
I have some suggestions for the patch. Kindly check.
Also Kindly name inter-diff as .txt not .patch. Then it will be ignored by the test cases.

1. +++ b/core/modules/help_topics/help_topics/breakpoint.overview.html.twig
   @@ -0,0 +1,21 @@
   +<p>{% trans %}Breakpoints are the point a which your sites content will respond to provide the user with the best possible layout to consume the information. A breakpoint separates the height or width of viewports (screens, printers, and other media output types) into steps. For instance, a width breakpoint of 40em creates two steps: one for widths up to 40em and one for widths above 40em. Breakpoints can be used to define when layouts should shift from one form to another, when images should be resized, and other changes that need to respond to changes in viewport height or width.{% endtrans %}</p>
   

   "... a which your sites content will ..."
   should be "... a which your site's content will ..."

2. +++ b/core/modules/help_topics/help_topics/color.changing_colours.html.twig
   @@ -0,0 +1,18 @@
   +<p>{% trans %}Change the color scheme scheme of your site such as the color of links, backgrounds, or text.{% endtrans %}</h2>
   

   "... color scheme scheme of ..." typo is there.

3. +++ b/core/modules/help_topics/help_topics/breakpoint.overview.html.twig
   @@ -0,0 +1,21 @@
   +<p>{% trans %}The <em>Breakpoint</em> module allows you to define breakpoints and breakpoint groups.Modules and themes can use the API provided by the <em>Breakpoint</em> module to define breakpoints and breakpoint groups, and to assign resolution multipliers to breakpoints.{% endtrans %}
   

   Add space after full-stop.

4. +++ b/core/modules/help_topics/help_topics/color.overview.html.twig
   @@ -0,0 +1,14 @@
   +  <li>{% trans %} The Color module saves a modified copy of the theme's specified stylesheets in the files directory.If you make any manual changes to your theme's stylesheet, <em>you must save your color settings again, even if you haven't changed the colors</em>. This step is required because the module stylesheets in the files directory need to be recreated to reflect your changes.{% endtrans %}</li>
   

   Add space after a full-stop.

Thanks @abhisekmazumdar , I have updated the patch with the changes you have mentioned.
@jhodgdon With respect to heading - Common Issues, I have moved it from color.changing_colors.html.twig to color.overview.html.twig and changed the heading Common Issues to Managing common issues.

check standards -- that is still not a standard heading! [sorry for brevity, my arm is in sling and I cannot type]

@jhodgdon I have updated the heading from "Managing common issues" to "Managing manual changes and theme compatibility"

Still not OK header. Pleas read standards page. (Sorry my arm in sling typing is very hard for next 2 weeks....)

Here is a new patch. What I did so far (see several of my previous reviews for why this was done):
- Added an appearance overview top-level topic. Put intro material about themes and layouts here.
- Made the other topics not top level; instead, related to this new topic.
- Consolidated the two color topics into one topic.
- Field layout module is currently experimental, so it doesn't need to be documented yet. The other two layout topics were basically copy/paste of the module overviews, so I moved the relevant information into the appearance overview topic and deleted them.

This issue still needs topics on the following tasks:
- Creating a layout, Assigning a layout to an entity type or sub-type, and possibly other Layout topics
- Installing/uninstalling a theme

The layout topics depend on topics that tell what an entity is and fields etc., as well as the block topics. The field/entity topics have been written on related issues, but they have not yet been added to Drupal, so I think we should postpone this topic until that other issue is completed. So, I'm uploading the patch as it is so far, and we can wait until that other issue is done before we finish it.

The field/entity topic patch got in, so this can be unpostponed. Still needs work for the additional needed topics (see previous comment).

Here is a new patch. It's the same as the last patch, with two new topics added on installing/uninstalling themes.

The patch is still not done [so still at Needs Work] -- it needs to have at least one topic written about using Layout Builder. I investigated what we need for that, and I think we need one topic about using Layout Builder to lay out the display of a content item (an administrator cannot define new layouts -- those come from modules/themes).

The procedure seems to be:
- Go to Manage Display for a content type, block type, or any other entity sub-type that has a Manage Display page [we have a topic on this already and a topic that explains entity sub-types; these should be linked to.]
- Check "Use Layout Builder" under "Layout options", and optionally check "Allow each ____ to have its layout customized" where ___ is the type of entity.
- Click Save
- Click "Manage layout"
- Blocks will be put into the layout by default for the fields of the entity sub-type. Add and remove additional blocks as needed. [this will need some explanation!!]
- I'm assuming that if your theme or modules provide more than one layout, you'd also be able to choose from available layouts, but I am not sure what that looks like, as Bartik doesn't have multiple layouts.

Notes from amykhailova in Slack about the Layout Builder:

(a) [I asked] Can Layout Builder (not counting any contrib or experimental modules) be used for anything other than providing a nicer Manage Display? [the hook_help suggests no but I wanted to check]

Amy's answer: Layout Builder is not just for Manage Display but it does start there. Out of the box you can not only place fields of the content type in different layout sections but also any custom blocks or create new custom blocks. It also allows to have layouts per content type - which is close to enhanced manage display but also per node - meaning that you can define and manipulate layout for the node that also can render views and blocks and fields. So I wouldn't call it just for manage display. The limitation is that it's meant for content entities but doesn't affect your footer and header and other potential theme regions

(b) [I asked] Is there a core/contrib theme/module that provides some additional layouts that I can try out? I will need to write help on how to choose a different layout, but it's hard to see what it would look like using Bartik, which as far as I can tell, only has one available layout defined (or that default one-section layout may even be defined in the system module, not sure, but anyway I seem to only have one available).

Amy's answer: There are a lot of modules to try out. I'd recommend looking at this page: https://www.drupal.org/docs/8/core/modules/layout-builder/additional-mod...

The ones that give additional layouts: Layout Builder Library, Layout Builder Kit
https://www.drupal.org/project/layout_library
https://www.drupal.org/project/layout_builder_kit

Oh, and I'm working on this as well as the linked User Guide issue...

Here is a new patch, which now includes I think all the topics we need here. Since as far as I know, no one has reviewed my previous patch (which was not really ready for review anyway), I didn't make an interdiff file. Hope that is OK.

@jhodgdon: thanks for working on this!

Another nitpick:

+++ b/core/modules/help_topics/help_topics/system.theme_uninstall.html.twig
@@ -0,0 +1,15 @@
+  <li>{% trans %}Click the <em>Uninstall</em> link to install the theme. If there is not an <em>Uninstall</em> link, the theme cannot be uninstalled because it is either being used as the site default theme or as the <em>Administration theme</em>.{% endtrans %}</li>

Should we add here that themes also cannot be uninstalled when the theme is a base theme of an activated subtheme used?

Oh, if that is true, definitely! Then we probably also need to explain what base themes are, which we haven't done... but I'm not sure that is true. Isn't Classy the base theme of Bartik? I don't think it stays installed all the time...

Hmmm... So that's an odd case. Classy is the base theme for Bartik, but it is labeled as Hidden in its info.yml file, so you don't see it on the Appearance page to be uninstalled.

So, I'm still not sure if base themes have to be kept as installed or not. ???

OK, sorry for so many comments! On my test site, I have some base themes and you are correct: if a sub-theme is installed, you cannot uninstall its base theme until you first uninstall the subtheme.

So, we do need to add that to the patch... here's an interdiff and a new patch. Thanks for taking the time to review!

@jhodgdon: Yeah the Bartik dependency is not obvious. Many users already humbled over this and wonder what is going on. I think it is a left-over from when we had issues with base themes and sub themes and how they should NOT be uninstalled/removed back in the D7 days. I never liked this exception and confusion but it maybe was unavoidable.

Thanks for investigating on it and for updating the patch on this! Awesome. You rock! Let me set it to RTBC if you don't mind since I didn't found any showstopper. Please take care and stay safe!

This issue is now blocking #3047711: Convert file, image, media, media_library, responsive_image module hook_help() to topic(s) so adding tag.

Committed and pushed 6ec59fd3a3 to 9.1.x and 40d0cbc222 to 9.0.x and 9c80c1d7f7 to 8.9.x. Thanks!

Backported to 8.9.x as this is text and an experimental module.