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.
Comment | File | Size | Author |
---|---|---|---|
#21 | revised-information-2390245-21.patch | 2.07 KB | zealfire |
#21 | interdiff-2390245-19-21.txt | 709 bytes | zealfire |
#19 | revised-information-2390245-19.patch | 2.07 KB | zealfire |
#19 | interdiff-2390245-17-19.txt | 559 bytes | zealfire |
#17 | revised-information-2390245-17.patch | 2.02 KB | zealfire |
Comments
Comment #1
zealfire CreditAttribution: zealfire commentedI 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.
Comment #2
jhodgdonFirst 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.
Comment #3
zealfire CreditAttribution: zealfire commentedThanks @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.
Comment #4
jhodgdonWe 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:
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)
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)
Let's put a more realistic example here, or maybe 'Description of what this module does.'?
i)
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.
Comment #5
zealfire CreditAttribution: zealfire commented@jhodgdon , thanks again for helping me again.I am submitting a new patch including all the requirements as suggested by you , so please review.
Comment #6
jhodgdonMuch better, thanks for the new patch!
Just a couple more things to fix:
a)
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)
Should be:
c) These lines are too long:
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)
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:
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.
Comment #7
zealfire CreditAttribution: zealfire commented@jhodgdon , thanks again for guiding me.I hope i have included all the requirements as suggested by you this time,so please review.
Comment #8
jhodgdonGreat! Just a few small things left to fix:
a) I missed this in my last review, sorry:
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)
Should be "extension, shown" not "extension ,shown".
d)
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:
e)
- First line: "you" should be "your".
- Second line: needs space in "version: VERSION".
f)
This doesn't make sense to me... Maybe:
If your module depends on other modules, list them here.
Comment #9
zealfire CreditAttribution: zealfire commented@jhodgdon,changes included as directed by you in new patch.Thanks
Comment #10
jhodgdonThere is still one space at the end of a line here (see #8 (b)):
(middle line)
The rest looks great!
Comment #11
zealfire CreditAttribution: zealfire commented@jhodgdon, thanks for correcting me.
Comment #12
zealfire CreditAttribution: zealfire commentedearlier didn't change the status.Thanks
Comment #13
jhodgdonThanks, 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.
Comment #14
alexpottThis is duplicated info - see InfoParserInterface
Let's just add an @see to that
@see \Drupal\Core\Extension\InfoParserInterface::parse()
Comment #15
zealfire CreditAttribution: zealfire commentedI have created this new patch including the above changes,so please review.
Thanks.
Comment #16
alexpottWhy not https://www.drupal.org/developing/distributions
Over the 80 character per line limit.
Comment #17
zealfire CreditAttribution: zealfire commentedPlease review.
Thanks.
Comment #18
jhodgdon@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:
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.
Comment #19
zealfire CreditAttribution: zealfire commentedSubmitting a patch along with interdiff file.Please review.
Thanks.
Comment #20
jhodgdonThanks! Looks good to me now, except that this sentence should be wrapped into the previous paragraph.
Comment #21
zealfire CreditAttribution: zealfire commentedSorry,for being ignorant everytime.Hopefully this time done it correctly.Please review.
Thanks.
Comment #22
jhodgdonOh, 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!
Comment #23
alexpottCommitted 596bc42 and pushed to 8.0.x. Thanks!
Thanks for adding the beta evaluation to the issue summary.