Problem/Motivation
#3041924: [META] Convert hook_help() module overview text to topics for the views, views_ui module(s).
Proposed resolution
Take the information that is currently in the hook_help module overview section for the module(s), and make sure the information is in one or more Twig help topic files. Steps:
- Find the hook_help() implementation function in the core/modules/MODULENAME/MODULENAME.module file(s). For example, for the core Contact module, the module files is core/modules/contact/contact.module, and the function is called contact_help().
- Locate the module overview portion of this function. This is located just after some lines that look something like this:
switch ($route_name) { case 'help.page.contact':
And ends either at the end of the function, or where you find another
case 'something':
line. - We want to end up with one or more topics about the tasks that you can do with this module, and possibly a section header topic. So, read the help and figure out a good way to logically divide it up into tasks and sections. See Standards for Help Topics for information on how to do this.
- See if some of these tasks are already documented in existing topics. Currently, all topics are in
core/modules/help_topics/help_topics
. Note that to see existing topics, you will need to enable the experimental Help Topics module (available in the latest dev versions of Drupal 8.x). - For each task or section topic that needs to be written, make a new Twig topic file (see Standards for Help Topics) in
core/modules/help_topics/help_topics
. You will need to choose the appropriate module prefix for the file name -- the module that is required for the functionality. Alternatively, if the information spans several modules or if the information should be visible before the module is installed, you can use the "core" file name prefix. For instance, it might be useful to know that to get a certain functionality, you need to turn on a certain module (so that would be in the core prefix), but then the details of how to use it should only be visible once that module is turned on (so that would be in the module prefix). - File names must be MODULENAME.TOPICNAME.html.twig -- for example, in the Action module, you could create a topic about managing actions with filename action.managing.html.twig (and "MODULENAME" can be "core" as discussed above).
- Make a patch file that adds/updates the Twig templates. The patch should not remove the text from the hook_help() implementation (that will be done separately).
Remaining tasks
a) Make a patch (see Proposed Resolution section).
b) Review the patch:
- Apply the patch.
- Turn on the experimental Help Topics module in your site, as well as the module(s) listed in this issue.
- Visit the page for each topic that is created or modified in this patch. The topics are files in the patch ending in .html.twig. If you find a file, such as core/modules/help_topics/help_topics/action.configuring.html.twig, you can view the topic at the URL
admin/help/topic/action.configuring
within your site. - Review the topic text that you can see on the page, making sure of the following aspects:
- The text is written in clear, simple, straightforward language
- No grammar/punctuation errors
- Valid HTML -- you can use http://validator.w3.org/ to check
- Links within the text work
- Instructions for tasks work
- Adheres to Standards for Help Topics [for some aspects, you will need to look at the Twig file rather than the topic page].
- Read the old "module overview" topic(s) for the module(s), at
admin/help/MODULENAME
. Verify that all the tasks described in these overview pages are covered in the topics you reviewed.
User interface changes
Help topics will be added to cover tasks currently covered in modules' hook_help() implementations.
API changes
None.
Data model changes
None.
Release notes snippet
None.
Comment | File | Size | Author |
---|---|---|---|
#43 | 3047723-43.patch | 9.75 KB | jhodgdon |
#34 | Screenshot at 2019-11-05 12-12-08.png | 14.21 KB | Gayathri J |
#27 | Screenshot at 2019-11-04 16-35-45.png | 139.17 KB | Gayathri J |
#27 | Screenshot at 2019-11-04 16-35-51.png | 134.03 KB | Gayathri J |
#27 | Screenshot at 2019-11-04 16-35-24.png | 225.15 KB | Gayathri J |
Comments
Comment #2
jhodgdonParent issue was committed, so we can un-postpone this now!
Comment #3
jhodgdonAdding views module to this issue.
Comment #4
adevms CreditAttribution: adevms at REEA commentedCreated a patch for views&views_ui.
Comment #5
adevms CreditAttribution: adevms at REEA commentedPatch wasn't correctly created. Remade.
Comment #6
jhodgdonThanks for the patches! I don't have time to review them today, sorry! I will look at them soon though, and your efforts are appreciated.
Comment #7
alonaoneill CreditAttribution: alonaoneill at Hook 42 commentedPatch applied via STM.The experimental Help Topics module was enabled (Added screenshot below).
Reviewed each topic that was created and modified in this patch. Reviewed the patch for spelling and grammar. The topics in the patch ending in .html.twig.
I uploaded screenshots with topics created.
I do see problems with this patch:
- We don't want topics called things like "Views module overview"/"Views UI module overview".
- Link provided in "Views overview" topic for "online documentation for the views module" doesn't take you to the actual documentation page, after clicking it just reload the page you're currently on ("Views module overview" topic). I added screen that shows that link.
Comment #8
jhodgdonUpdated issue summary with better instructions/guidelines
Comment #9
jhodgdonAnother iteration on guidelines.
Comment #10
jhodgdonWe've migrated the help topic standards to https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... so updating issue summary again.
Comment #11
jhodgdonI will make the next patch for this issue in the next few days.
Comment #12
jhodgdonI had less time than i thought I would.
Comment #14
jhodgdonWe 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.
Comment #15
jhodgdonComment #16
spitzialist CreditAttribution: spitzialist at Unic commentedWorking on this at DrupalCon Amsterdam :)
Comment #17
chipway CreditAttribution: chipway at Chipway commented@spitzialist,
Welcome and thanks to contributing. I would recommend not to assign the issue to yourself, because your comment already says that you are working on it.
Before leaving unassign it please.
You may also say that you are working with "XXX" mentoring you if it the case?
My 2 cents,
Enjoy!
Comment #18
spitzialist CreditAttribution: spitzialist at Unic commentedI sadly had some issue with my infrastructure and need to come back later, so unassigne.
Comment #19
narnua CreditAttribution: narnua commentedI am taking a look into this at Amsterdam 2019 contrib session
Comment #20
narnua CreditAttribution: narnua commentedRerolled the patch against 8.9.x, just adding the label and top_level tags in the new format. (based on the observation that drush cr failed due to these tags being in a format no longer supported)
Note: I did not revise the actual content of the Views+Views UI help topics (presuming these were already worked on by topic experts), only fixed what was not working in the previous version of the patch (5), so that the Views and Views UI documentation links would be visible on the Help topics dashboard page.
Comment #21
narnua CreditAttribution: narnua commentedComment #22
narnua CreditAttribution: narnua commented@jhodgdon, you pointed out in #14 that Twig templates are required to be under Help topics module, rather than the Views/Views UI modules. Is this still the case?
While working on rerolling the the patch (updating to new formatting), it seems to me that the help topics appear just fine on the Help topics dashboard, when the twig templates are under the views+views ui modules.
Comment #23
irenebreiner CreditAttribution: irenebreiner at Aperto GmbH - An IBM Company commentedThe patch in #21 worked for me.
Before applying the patch:
After applying the patch Views overview and Views UI overview show up at topics:
Comment #24
jhodgdonYes, the help topics appear just fine if the topics are in the views module (or anywhere else). But for now, we do want the topics under help_topics. See #14.
Also, just to be clear: Please read the information in the Help Topic Standards page (see link in issue summary) about how to divide help up into topics. We don't want to have one topic that is an overview of a module. We want to have topics that tell you how to use Drupal. This patch is just two module overviews. That is not what we want.
Thanks!
Comment #25
jhodgdonAs I said in my previous comment, the patches here are not at all what we are looking for -- see https://www.drupal.org/docs/develop/documenting-your-project/help-topic-... and the issue summary here.
I'm going to make a new patch.
Comment #26
jhodgdonHere's a new patch. I did not make an interdiff, because it was not based on the previous patches.
Comment #27
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commented#26 I applied the patch its looking good.
In views_ui.edit topic coming website encountered error in my system , its showing -> Twig\Error\RuntimeError: An exception has been thrown during the rendering of a template ("Route "help.help_topic" does not exist."). in Twig\Template->displayWithErrorHandling() (line 8 of /var/www/html/drupal-8.9/core/modules/help_topics/help_topics/views_ui.edit.html.twig).
Im trying to fix this error.
views_ui.add_display: After step 4 i think so we need to explain about FORMAT, FIELDS, FILTER CRITERIA , SORT CRITERIA and how to use advanced field set. I saw all mentioned in views_ui.edit topic but i think so we need to mention clearly in views_ui.add_display topic.
I would like to work on this issue can you comment above mentioned things are required or not.
Thank you!
Comment #28
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commentedComment #29
jhodgdonRegarding the Twig error, I am not getting that error. Make sure you do a git pull before applying this patch. I think maybe you are running on an old version of Drupal Core before we changed the route names. Either that or maybe you need to run a cache rebuild.
Regarding add display, I do not want to repeat the information that is in the Edit topic (which you haven't seen apparently, due to the Twig error), in the Add Display topic. I think I should have made this into a link to that topic though. I will make a new patch within an hour.
Comment #30
jhodgdonHere's a new patch that makes a link to the related topic. I'm also going to make a follow-up issue to add some more links in existing topics.
Comment #31
jhodgdonWhoops, I forgot a word in that last patch. It should read "Follow the steps in Editing an existing view display to edit..." (the word "to" was missing). Here's the updated patch.
Comment #32
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commented#29 Thanks for the comment, regarding twig error i will check.
Add Display topic link to edit topic that was good, i accepted that again we no need to repeat content.
Comment #33
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commentedI think so maybe no need to mention routing we can do link this i attached screenshot.
Comment #34
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commentedComment #35
jhodgdonI'm not sure what you are suggesting? The latest patch now says:
That will turn it into a link to the "Editing an existing view display" topic. ... Oh, I see what you are suggesting, just putting the topic ID in there for the URL.
If we did it that way, we would be implicitly assuming that the URL of topics must end in the topic ID. That is currently how URLs for topics are made, but it could be changed in code and then this would not work. It is better to ask the system to make the correct URL.
Comment #36
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commentedHi jhodgdon
Thanks for the comment i accepted this.We need some more links and explanation i am going to work on this issue can u suggest me.
Comment #37
jhodgdonI don't think this patch needs any work. What do you think it needs?
Comment #38
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commentedI am not thinking anything, just i am asking if it maybe require some work can u suggest me that's it.
Comment #39
jhodgdonAs far as I am concerned, all it needs is a full and careful review/test (see issue summary for all the things to review/test). When it is satisfactory, someone needs to mark it "Reviewed and Tested by the Community".
Comment #40
Amber Himes MatzThe patch in #31 contains 4 new topics all related to the Views module.
1. views.overview.html.twig: Looks good. Excellent succinct overview of views.
- There is the tiniest of typos (a missing period after the abbreviated "etc" on line 17). This is a very minor nit.
- I think we should be encoding
>
as>
on lines 21, 22, and 23. This should be fixed.2. views_ui.add_display.html.twig: Verified steps. Looks good.
- Again, we should be encoding greater-than signs as
>
(one in line 13).3. views_ui.create.html.twig:
- Encode greater-than sign as
>
(line 13).4. views_ui.edit.html.twig: Excellent instructions that would apply to all views displays.
- Encode greater-than sign as
>
(line 13).Comment #41
Amber Himes MatzComment #42
Amber Himes MatzMy apologies! I just realized that my IDE settings were rendering encoded greater-than signs in an effort to be helpful! (It turns out, this was not helpful.)
The patch in #31 looks fine. Setting this to RTBC.
Comment #43
jhodgdonFixing the very minor typo you found in #40 -- added a . after etc in
by editing the patch. Since this one . is all I changed, leaving at RTBC.
Comment #44
Amber Himes MatzLooks great, thank you @jhodgdon! +1 to keep this at RTBC.
Comment #45
Gayathri J CreditAttribution: Gayathri J at UniMity Solutions Pvt Limited commented#43 patch looking good.
Comment #47
jhodgdonTest failed with
I'll put this back to RTBC.
Comment #49
jhodgdonSame unable to start server message. Ugh.
Comment #51
jhodgdonUnrelated test fail.
Comment #52
jhodgdonComment #54
larowlanThis looks good to me, I tried it out locally and I think the content is a good primer on what is a complex piece of the Drupal UI.
This lead me to think about whether there is merit in giving the topics a relative complexity, such as 'Advanced / Basic / Moderate' so that people who're evaluating the topic can gauge whether it is a good fit for their skills.
In the user-guide we signal this with 'Prerequisite knowledge' so I think its probably something to discuss a bit wider if we need something similar with these topics, or if referring people to the user-guide is sufficient.
Comment #56
larowlanCommitted 2651a49 and pushed to 9.1.x. Thanks!
Comment #57
jhodgdonThe way I see it, the Help Topics should be the minimum necessary to be able to understand and manage a site, and cover the most common things people need to do. The User Guide has a lot more content... I am not sure about beginning/intermediate/advanced, but we could create an issue to do that and discuss further.