Child of #2323895: [Meta] Document format/content of various YML files (we have been discussing how to document *.yml files).

There is a topic https://api.drupal.org/api/drupal/core!modules!system!core.api.php/group... that talks about modules, themes, and profiles.

It has two problems:

a) The link about Distributions/Profiles goes to a page on drupal.org that is more about what they are than how to develop them. It should be linking to https://www.drupal.org/node/159730 instead.

b) There is no information on api.d.o about the *.info.yml file syntax. So we need to add sections to this topic about this file syntax. The easiest way is probably to give minimal examples of the syntax for a theme, a module, and a profile.

Probably a good Novice project?

Beta eval: This is a Normal Task, but it is documentation-only and not disruptive, and is therefore allowed to be committed during Beta or even after release for that matter.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

zealfire’s picture

Assigned: Unassigned » zealfire
Category: Bug report » Task
Status: Active » Needs review
FileSize
689 bytes

I am a newbie,i think i have solved problem mentioned in first point need help in second one.For first point i have changed the link in core.api.php page.

jhodgdon’s picture

Status: Needs review » Needs work

First point, good! I'm setting this back to Needs work because we need to do the second part too.

For the second point, I think we should:

a) There are already really two sections in this topic (the first one lists the types of extensions, and the second lists methods that modules can use to extend and alter Drupal's behavior). They should each have section headers added to them. See
https://www.drupal.org/node/1354#section

b) I think instead of using the term 'add-on' we should use 'extension' throughout this topic.

c) Add a third section at the bottom, with section title "*.info.yml files". In this section, start with a short explanation... something like this:

Extensions must each be located in a directory whose name matches the short name (or machine name) of the extension, and this directory must contain a file named machine_name.info.yml (where machine_name is the machine name of the extension). The syntax of the file is similar for modules, themes, and installation profiles. Here is a sample:

d) Put in a sample module .info.yml file within @code/@endcode tags (see https://www.drupal.org/node/1354#code ). Add some comments (using #) to explain what each line is.

zealfire’s picture

Title: Extending topic needs more information and better link » Information about *.info.yml file syntax has been provided
Status: Needs work » Needs review
FileSize
3.33 KB

Thanks @jhodgdon for helping me out earlier.I have made the changes as diredted by you earlier though i have some doubts over the example which i have given and the way i have done commenting.

jhodgdon’s picture

Title: Information about *.info.yml file syntax has been provided » Extending topic needs more information and better link
Status: Needs review » Needs work

We do not normally change the issue title in this way, so resetting the title.

Thanks for the new patch! It is very good. A few small things to fix:

a) For people reading the documentation in the PHP file and not on api.drupal.org, I think it would be very helpful if there was a blank line before each @section line. Can you put that in?

b) Each section needs to have a unique identifier. So you put in
@section sec_description
for all of them. They should be instead something like
@section sec_types
@section sec_alter
etc.

c) "alterification" is not a word. :) So I think the second section header should be:
Alteration methods for modules

d) I don't think we need these lines, since the text already has this information:

+ * # The .info.yml file should have the same unique name as the .module file (if any) 
+ * # and reside in the same directory. For example, if your module is named "Example," 
+ * # and has a example.module file, then your .info.yml file should be named example.info.yml

e) Formatting: Each comment in the sample info.yml file should be sentences. So start each comment with a capital letter and end with a . Sentences should be separated by one space or a newline, and there should be a space between the # and the comment on each comment line. The indentation of the non-comment lines also needs some attention.

f) I think we should add a short comment before the name: line explaining that this is the human-readable name of the extension, shown in the UI.

g)

+ * name: Example Module

This is not a good example, because we do not normally put "Module" in the name of modules. How about just calling it "My Example"? I think two-word strings also need to be in '' quotes?

h)

+ * description: Example Module description.

Let's put a more realistic example here, or maybe 'Description of what this module does.'?

i)

+ * # the version number will be filled in by the packaging script, you should not specify it
+ * # manually, but leave out the version line entirely
+ * version: 1.0

In Drupal Core and also in Contrib modules I think you're supposed to put "version: VERSION" in there... this comment is confusing with the example though... If someone is making their own custom module they would put a version number in there, right? Let's clarify that in the comment.

zealfire’s picture

Status: Needs work » Needs review
FileSize
3.17 KB

@jhodgdon , thanks again for helping me again.I am submitting a new patch including all the requirements as suggested by you , so please review.

jhodgdon’s picture

Status: Needs review » Needs work

Much better, thanks for the new patch!

Just a couple more things to fix:

a)

+ * Here is a sample(module.info.yml):

Needs a space before (module.info.yml)... and I think maybe it should say (for a module) not (module.info.yml) since module.info.yml is not an actual file name that you should use.

b)

+ * # This can be a human-readable name of the extension ,shown in the UI. 

Should be:

* # Human-readable name of the extension, shown in the UI.

c) These lines are too long:

+ * # This key is used to group like modules together. In this case 'Custom' is used to
+ * # group all of your projects custom modules together making them easier to locate and enable.

Please wrap everything at 80 characters. And maybe this should say "... group related modules together in the UI" rather than "group like modules together"? I think we can actually get rid of the second sentence too -- it just seems redundant.

d)

+ * # It is required and indicates the type of extension, e.g. module, theme or profile.

Take out "it is required and indicates". Also, ... Let's just say:
Type of extension: module, theme, or profile.

e) This is also longer than 80 characters:

+ * # The version number will automatically be added for contributed themes but you can write your own if 
+ * # if your theme is not being hosted on drupal.org infrastructure. 

Also I do not think this is clear yet, and it should not suddenly be talking about themes. How about:

For custom modules, define a version number. If your extension is on drupal.org, use version: VERSION and the packaging scripts will insert the version.

f) I guess I told you to use complete sentences in the # documentation lines... It seems to have made some things excessively wordy, so maybe we should drop that. For instance:
This key can be used to specify the route for the administration page.
--> could be:
Route for the main administration page.

zealfire’s picture

Status: Needs work » Needs review
FileSize
2.9 KB

@jhodgdon , thanks again for guiding me.I hope i have included all the requirements as suggested by you this time,so please review.

jhodgdon’s picture

Status: Needs review » Needs work

Great! Just a few small things left to fix:

a) I missed this in my last review, sorry:

+ * Overview of extensions and alteration methods for Drupal.
+ 
+ * @section sec_types Types of extensions

The "blank" lines before @section actually still need to start with * :) This is in several spots in the patch.

b) In the latest patch there are a few lines with blank spaces at the ends of lines. This is not good. If you want to keep contributing to Drupal, you may want to investigate whether your programming editor can either highlight or remove trailing whitespace on all lines, as this is the Drupal project coding standard. Most programming editors can be set up to do that.

c)

+ * # Human-readable name of the extension ,shown in the UI. 

Should be "extension, shown" not "extension ,shown".

d)

+ * description: Description of what this module does.

I think the description needs to be enclosed in ' quotes? Also I don't think we normally use " quotes in yml files, so check the rest of the sample for that. For instance here is the core block_content.info.yml file:

name: 'Custom Block'
type: module
description: 'Allows the creation of custom blocks through the user interface.'

e)

+ * # For custom modules, define a version number. If you extension is on drupal.org,
+ * # use version:VERSION and the packaging scripts will insert the version. 

- First line: "you" should be "your".
- Second line: needs space in "version: VERSION".

f)

+ * # The optional dependencies keys provided by Drupal with a list of modules.

This doesn't make sense to me... Maybe:

If your module depends on other modules, list them here.

zealfire’s picture

Status: Needs work » Needs review
FileSize
2.88 KB

@jhodgdon,changes included as directed by you in new patch.Thanks

jhodgdon’s picture

Status: Needs review » Needs work

There is still one space at the end of a line here (see #8 (b)):

+ * Overview of extensions and alteration methods for Drupal.
+ * 
+ * @section sec_types Types of extensions

(middle line)

The rest looks great!

zealfire’s picture

@jhodgdon, thanks for correcting me.

zealfire’s picture

Status: Needs work » Needs review
FileSize
2.88 KB

earlier didn't change the status.Thanks

jhodgdon’s picture

Issue summary: View changes
Status: Needs review » Reviewed & tested by the community

Thanks, looks good!

By the way, for your next (I hope) contribution:

a) When changing the status, you do not have to upload the same patch file again.

b) In general when working on an issue, when there is already one patch (yours or someone else's) and you make a new patch, you should provide an interdiff file. I didn't ask for one on this issue because the patches were pretty small, but in general it is a good idea. See https://drupal.org/documentation/git/interdiff for instructions.

c) I added a "beta evaluation" to the issue summary.

alexpott’s picture

Status: Reviewed & tested by the community » Needs work
+++ b/core/modules/system/core.api.php
@@ -1025,6 +1027,33 @@
+ * The syntax of the file is similar for modules, themes, and installation profiles.
+ * Here is a sample (for a module):
+ * @code
+ * # Human-readable name of the extension, shown in the UI.
+ * name: 'My Example'
+ * # Text that is shown on the module administration page.
+ * description: 'Description of what this module does.'
+ * # This key is used to group related modules together in the UI.
+ * package: Custom
+ * # Type of extension: module, theme, or profile.
+ * type: module
+ * # For custom modules, define a version number. If your extension is on drupal.org,
+ * # use version: VERSION and the packaging scripts will insert the version.
+ * version: VERSION
+ * # Specifies the version of Drupal core that your module is compatible with.
+ * core: 8.x
+ * # If your module depends on other modules, list them here.
+ * dependencies:
+ * - node
+ * # Route for the main administration page.
+ * configure: example.admin_index.
+ * @endcode

This is duplicated info - see InfoParserInterface

Let's just add an @see to that @see \Drupal\Core\Extension\InfoParserInterface::parse()

zealfire’s picture

Status: Needs work » Needs review
FileSize
2 KB

I have created this new patch including the above changes,so please review.
Thanks.

alexpott’s picture

Status: Needs review » Needs work
  1. +++ b/core/modules/system/core.api.php
    @@ -1005,8 +1006,9 @@
    - *   information, see https://drupal.org/documentation/build/distributions.
    + *   information, see https://www.drupal.org/node/159730.
    

    Why not https://www.drupal.org/developing/distributions

  2. +++ b/core/modules/system/core.api.php
    @@ -1025,6 +1027,12 @@
    + * Extensions must each be located in a directory whose name matches the short name
    + * (or machine name) of the extension, and this directory must contain a file named
    + * machine_name.info.yml (where machine_name is the machine name of the extension).
    

    Over the 80 character per line limit.

zealfire’s picture

Status: Needs work » Needs review
FileSize
2.02 KB

Please review.
Thanks.

jhodgdon’s picture

Status: Needs review » Needs work

@zealfire: Please make interdiffs when you post new patches, thanks!

@alexpott: Thanks for noticing the URL alias and the duplicated information -- I wasn't aware it was documented.

In the latest patch:

 *
+ * @section sec_sample *.info.yml files
+ * Extensions must each be located in a directory whose name matches the short
+ * name (or machine name) of the extension, and this directory must contain a
+ * file named machine_name.info.yml (where machine_name is the machine name of
+ * the extension).
+ * @see \Drupal\Core\Extension\InfoParserInterface::parse()

Using @see here is not a good idea. @see puts the link into a See Also section at the bottom of the documentation. What is needed here instead is a sentence something like:

See \Drupal\Core\Extension\InfoParserInterface::parse() for documentation of the format of .info.yml files.

zealfire’s picture

Status: Needs work » Needs review
FileSize
559 bytes
2.07 KB

Submitting a patch along with interdiff file.Please review.
Thanks.

jhodgdon’s picture

Thanks! Looks good to me now, except that this sentence should be wrapped into the previous paragraph.

zealfire’s picture

Sorry,for being ignorant everytime.Hopefully this time done it correctly.Please review.
Thanks.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Oh, no problem! It is quite normal for everyone's patches to go through several review/needs work cycles before they are committed. That is why we have reviews. Also, new contributors are never aware of all of our code/docs standards. You're doing great!

And this latest patch looks good to me. Thanks!

alexpott’s picture

Status: Reviewed & tested by the community » Fixed

Committed 596bc42 and pushed to 8.0.x. Thanks!

Thanks for adding the beta evaluation to the issue summary.

  • alexpott committed 596bc42 on 8.0.x
    Issue #2390245 by zealfire: Extending topic needs more information and...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.