Create Starterkit readme

I guess something to take into account is that this README ends up in all of the themes generated with Starterkit unless we add a specific step to remove it. We should take that into account as we write docs in that file.

Re: #4, oh, that I think negates my suggestion about adding in the sample command.

It's also actually a really good opportunity to link the docs to explain where the theme came from. We could also explicitly say "Themes generated from core's default Starterkit markup will include this README" or something to give both core devs and theme devs that clarity (and to keep the file from becoming confusing in the future).

I'm wondering if we should have another README which we'd use for replacing the README on the repository when a new theme is generated 🤔

Makes sense 👍

I applied the MR locally and read the README. It reads well but as someone who doesn't know theming I have some questions.

1. What is the difference between generating and creating as using in the README? The first paragraph emphasizes that Startkit is for 'generating new themes'. Then later it says Startkit is for creating new themes. Then the next sentence is back to generating. Can the same verb be used?

2. The wiki page linked to for more information would not help me to know how to use Starterkit. The first paragraph on that page has instructions for creating a theme, Does that belong on this page or somewhere else? It is the second paragraph that tells me how to create a theme using Starterkit, but that is already in the README. And the third section is about using git. Where do I go to get more information about making a theme? It is not for this issue, but can the wiki page link to somewhere to get me started?

3. The other READMEs in core/themes have a last section of 'About Drupal Theming'. Should that section be here as well?

The wiki page linked to for more information would not help me to know how to use Starterkit.

Can you clarify this? The page explains how to use Starterkit in detail. What is missing?

@bnjmnm, thanks, it makes more sense to me now.

#11. Ah, I have reread everything and I see my error. Section 2 does have more detail to help someone.

I then tried the command from the README and the wiki page and they all fail for me. For example,

/var/www/html$ php core/scripts/drupal generate-theme my_new_theme
PHP Warning:  rename(): The first argument to copy() function cannot be a directory in /var/www/
html/core/lib/Drupal/Core/Command/GenerateTheme.php on line 255

Warning: rename(): The first argument to copy() function cannot be a directory in /var/www/html/
core/lib/Drupal/Core/Command/GenerateTheme.php on line 255
PHP Warning:  rename(/tmp/drupal-starterkit-theme-4d29d66ba84cfbc7b794cda7f2af844b62fd76f0d4ecc4
.41519162,themes/my_new_theme): Invalid cross-device link in /var/www/html/core/lib/Drupal/Core/
Command/GenerateTheme.php on line 255

Warning: rename(/tmp/drupal-starterkit-theme-4d29d66ba84cfbc7b794cda7f2af844b62fd76f0d4ecc4.4151
9162,themes/my_new_theme): Invalid cross-device link in /var/www/html/core/lib/Drupal/Core/Comma
nd/GenerateTheme.php on line 255
                                                                    
 [ERROR] The theme could not be moved to the destination: themes/my_new_theme. 

Is there a missing step?

I don't get the same errors as @quietone, but something is indeed wrong with the commands in both the README and the handbook page. I used 9.5.x.

This works:

[ayrton:drupal-test-site | Wed 18:46:59] $ cd themes
[ayrton:themes | Wed 18:47:02] $ pwd
/Users/xjm/git/drupal-test-site/themes
[ayrton:themes | Wed 18:47:03] $ php ../core/scripts/drupal generate-theme my_new_theme
Theme generated successfully to themes/my_new_theme

Note the ../ in the relative path, which is missing from the handbook page.

I'll document what did not work next but posting this so @quietone can see also.

This does not work:

[ayrton:themes | Wed 18:50:22] $ php ../core/scripts/drupal generate-theme --starterkit starterkit my_new_theme
[ERROR] Theme source theme starterkit cannot be found.                         

Nor does this:

[ayrton:themes | Wed 18:50:29] $ php ../core/scripts/drupal generate-theme --starterkit ../core/themes/starterkit my_new_theme
[ERROR] Theme source theme ../core/themes/starterkit cannot be found.          

Maybe the theme needs to be enabled on the Drupal site, which Starterkit won't be?

Tried Olivero, but it's missing the magic:

[ayrton:themes | Wed 18:51:34] $ php ../core/scripts/drupal generate-theme --starterkit olivero my_new_theme
[ERROR] Theme source theme olivero is not a valid starter kit.

#14 does not work for me, I get the same errors. Perhaps related to the fact that I use ddev?

Oh, the theme is called starterkit_theme. This works:

[ayrton:themes | Wed 18:55:16] $ php ../core/scripts/drupal generate-theme --starterkit starterkit_theme my_new_theme_2
Theme generated successfully to themes/my_new_theme_2

So I think we should remove the default commands from the README, contrary to my earlier suggestion, and just link the docs.

I made these changes to the handbook page:
https://www.drupal.org/node/3283954/revisions/view/12737292/12756376

We still need to figure out if there's issues with the script and/or relative paths for ddev causing the errors @quietone is getting.

NW for the simple change of removing the slightly bugged instructions in favor of just linking the handbook page where we can explain it better. We might want someone to try to reproduce @quietone's issue also, but that's a separate bug to file if so.

OK actually the relative path thing is not necessary. This also works:

[ayrton:drupal-test-site | Wed 20:54:30] $ php core/scripts/drupal generate-theme --starterkit starterkit_theme my_new_theme_3
Theme generated successfully to themes/my_new_theme_3

The confusing text is:

A new theme can be generated in the /themes directory by running the following command:

I read this as " You should navigate to your themes directory and then run this command." But what it actually means is that the script writes to drupal_root/themes. If that's hardcoded, it could easily cause problems on environment setups like ddev's where the docroot and relative paths are different from the default core install.

I reverted my previous, incorrect change re: the relative path, and improved the docs so others won't have the same misunderstanding I did:
https://www.drupal.org/node/3283954/revisions/view/12756376/12756426

Made #3304433: generate-theme scripts fails in a ddev environment and uploaded a patch that does a recursive copy instead of rename.

I read the changes to the wiki page and I agree with the improvements, some of which I was planning on doing.

For the separate proposed README for generated themes.

Found some minor things!

One nitpick (feel free to disregard); one minor question, and one more slightly bigger question. Also, this issue is still tagged for a follow-up.

Beyond all that, I think this is RTBC.

I think that looks good. I gave it a brief manual test and confirmed that it does what the code indicates.

Cut and print, I say!

And uploading a patch so this can be tested against the lower branches.

Committed to 10.1.x, 10.0.x, and 9.5.x. Thank you!

I thought about whether to back port this to 9.4. The only changes are when you generate a new theme; it is not like it is going to overwrite an existing theme. So the main change at runtime is the addition of a readme for the base theme. I think this is an improvement for documentation and therefore allowed in a patch with this, so I backported it to 9.4 as well.

I think this is also the last stable blocker for Starterkit! 🎉 #3305560: Expand the readme added to starterkit-generated themes. is more of a should-have or a could-have.