Convert basic_auth, hal, jsonapi, rdf, rest, serialization module hook_help() to topic(s)

Created patch at Drupalcon 2019! Copied content from hook_help

Hi @DrupalCon19 and I am going to review this patch now

Updated to fix typo.

Changed opening line of text so "the" not updated.

Reviewing and testing with my mentoree @Andy Farmer

Replacing older patches that accidentally committed changes from parent issue patch

Thanks to

• @James.Shee for creating the issue
• @petedussin for the patches
• @aburrows and @Andy Farmer for reviewing!

We're going to need a better way to deal with the link to the Rest modules help page. The issue right now is that the link isn't going to work if the Rest module isn't enabled. The link will render appropriately, but when you click it you'll get a 404. This is handled in the current hook_help implementation by using the module service to check if the Rest module is enabled before linking to it.

(\Drupal::moduleHandler()->moduleExists('rest')) ? \Drupal::url('help.page', ['name' => 'rest']) : '#'])

There's not really a Twig friendly way of doing this. It's mentioned in this issue https://www.drupal.org/project/drupal/issues/3027054#comment-12934232 but without a method to resolve it yet.

Removed escape for apostrophe. Works without it.

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!

We're adding some more modules to this issue. So, it needs more in the patch. I haven't reviewed the existing patch yet. None of the other modules were started yet.

Regarding linking to the module help pages, the answer is don't do it! Those links were for when we had module overview help pages, and we will not have them any more. So if you mention another module, just say something like

the core Node module

and don't make it a link.

Updated issue summary with better instructions/guidelines

And one more iteration on the guidelines.

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

I have added overviews for newly added modules in this issue. Please review and add feedbacks. Thanks!. Not adding an interdiff as the difference in the patches is only addition of overview for new modules. I haven't changed anything in basic auth overview.

Thanks for the patch... But please read the instructions in the issue summary. We do not want module overview topics at all. What we want is task-oriented topics.

Tagging for badcamp2019, thanks! (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.

Tagging for DrupalCon Amsterdam 2019

I am going to help mentor a table at Amsterdam 2019 to work on moving this issue forward.

Hi, my name is Juraj Chlebec and i would like work on patch to this issue :)

I'm taking screenshots of the patch results to check if the solution is working.

I'm Vitor and I am at the DrupalCon Amsterdam 2019 and I am going to write a patch for this issue

Hi, I'm Christian, I'm @ DrupalCon2019 in Amsterdam and I'm trying to Review the issue.

Hi i'm Christopher Braun and i will apply and test the patch.

Hi I'm Joyce and I'll be helping testing/reviewing the patch.

@vladigor is also participating and pairing with Vitor here at Amsterdam2019. They do not have a laptop.

I create patch which move files to core/modules/help_topics/help_topics and fix metadata.

Interdiff of previous patch with current patch

Checked Path and Interdiff.

Topic Twig files where created for modules basic_auth, hal, jsonapi, rdf, rest, serialization in core/modules/help_topics/help_topics.

Great work!

There is an error in the Topic Twig for rdf. Label is "basic Auth" but should be RDF.

During Review of #34 I expected the following Issues:
HTTP Basic-Auth Help Page Shows RDF Help Page Content if Basic Auth isn't enabled:
If you click on Help in the Menu Bar and after that on "HTTP Basic Auth", it points you to "/admin/help/topic/rdf.overview".
Probably this is caused by a wrong label in rdf.overview.html.twig

Hi, thanks for the patch.

In the admin/help, the link to 'HTTP Basic Authentication' is displayed twice. See also screenshot.

One link goes to the HTTP Basic Authentication(admin/help/topic/basic_auth.overview), the other link goes to the RDF(/admin/help/topic/rdf.overview).

Fix for some minor issues in patch #34 also made by Havran

Removed meta tags to be consistent with other help topics from HAL topic and also removed a "." typo.

Changed label for RDF help topic as well.

Also uploaded interdiff from previous patch

Thanks for the new patch! The label was changed and we can now see the difference between HTTP Basic Auth and RDF. Everything worked as we expected.

I updated the summary a little bit to be coherent with the modules we are using.

The previous patch had no functionality issues but a typo in 'JSON:API'. #42

I am reviewing #46 at Amsterdam2019

Confirmed that the spelling correction is present. Still RTBC.

Thank you for all the thorough screenshots, reviews and patches. The contributors here found a couple of bugs in the initial patch, and fixed them. The patch in #46 will create the help topic files within the help topic module instead of their respective core modules.

Good job, everyone working on the issue today at DrupalCon Amsterdam 2019: oanailea, joyceCY, ChrisBee, christian.gerdes, Vitor Faria, havran, vladigor, and _m.

Thanks for the patches and reviews!

However, I don't think we want all these top-level topics for these somewhat esoteric subjects. We want to keep the main Help page fairly short, so people can find topics of interest quickly. So... This information is all background (no tasks)... Can we make just one top-level topic with the title of "Overview of web services" or something like that (not sure if that is the right overview topic name), and maybe just put all of this information in that one topic?

Another problem:

+{% set field_help_url = render_var(path('help.page', {'name': 'field'})) %}
+{% set hal_help_url = render_var(path('help.page', {'name': 'hal'})) %}
+{% set basic_auth_help_url = render_var(path('help.page', {'name': 'basic_auth'})) %}
+{% set node_help_url = render_var(path('help.page', {'name': 'node'})) %}

We definitely do *not* want to be linking to the old hook_help pages for these modules. We are going to be getting rid of the hook_help pages. Instead, use the "related" meta-data field at the top to make links between related Help Topics.

I think @jhodgdon has a good idea here.

I added the Needs issue summary update to follow-up to make sure that the issue summary contains the new proposed resolution.

OK, updated the issue summary. We have a standard issue summary, from Proposed Resolution on down, for these "convert" issues, which I think covers the idea that we *don't* want module overview topics. And we update it from time to time, via copy/paste, so I don't want to make changes to the Proposed Resolution step. So what I did was add a note to the top problem/motivation section instead. In bold type. :)

Created patch to have all the web services related at one place.

This is looking pretty good, thanks for the patch! A few things to look at:

a) "Web service provides an interface, to be utilized by another Web server or by a mobile app." ... This sentence needs some grammar attention... Maybe just needs to start with "A" or "The"? I am not sure.

b) HTML nitpick: the headings changed from H3 to H2 after the first one. They should all be H3 I thin.

c) A few of the headings don't start with "What is" or "What are". They should.

d) It bothered me that in a section like "What is JSON:API" the answer started out with "the xyz module provides". I think we should start by explaining what JSON:API is, and then after answering the question in the heading, point out that the module is available to implement it. This applies to multiple sections. I think the information is there -- just the order bothered me (leading off with the module instead of answering the question). I think that must have been copy/pasted from the module overview hook_help topics, which are trying to answer the question about what a specific module does, but we are moving away from module-oriented help here, towards concept-oriented and task-oriented help (i.e., oriented towards what people want to do with their web site, and the concepts they need to understand to do it).

e) The "for more information" links... only include if they are actually useful and contain information not in this topic. Also they're generally supposed to be at the end in their own section.

f) The DL list under the RESTful web services section doesn't have any context introducing it, so it doesn't really seem to make sense. If it is giving steps, maybe it should be in its own topic, like "Setting up RESTful web services"?

I'm working on a new patch for this now.

Here's a new patch... interdiff is not useful because pretty much every line in the topic changed. I updated the structure, simplified down to the essential information, and reorganized.

@jhodgdon Patch LGTM. The patch provides all basic information about web services and Modules that can be used to enable web services with Drupal.

Thanks for reviewing!

Unrelated test fail:

Drupal\Tests\jsonapi\Functional\EntityFormModeTest::testRelated
Drupal\Core\Database\SchemaObjectExistsException: Table sequences already exists.

1. +++ b/core/modules/help_topics/help_topics/core.web_services.html.twig
   @@ -0,0 +1,28 @@
   +---
   +<h2>{% trans %}What are web services?{% endtrans %}</h2>
   +<p>{% trans %}According to the <a href="https://www.w3.org">W3C</a>, a web service is a software system designed to support interoperable machine-to-machine interaction over a network. In other words, a web service is any software that allows two or more servers, computers, or mobile devices (machine-to-machine) to exchange information and/or instructions (interoperable interaction) across the Internet or a local area network. Typically, the data is transported via <a href="https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol">HTTP</a> in a machine-readable file format.{% endtrans %}</p>
   +<h2>{% trans %}What is serialization?{% endtrans %}</h2>
   

   The long explanation of what a web service is feels like it should ideally be a footnote rather than a standfirst. I was expecting something more like 'Web services allows your Drupal site to expose data to other websites and services in various formats'.

2. +++ b/core/modules/help_topics/help_topics/core.web_services.html.twig
   @@ -0,0 +1,28 @@
   +<p>{% trans %}Serialization is the process of converting complex data structures into text strings, so that they can be exchanged and stored (for example, for transmission over the Internet or for storage in a local file system). The reverse process is called <em>deserialization</em>. JSON and XML are the two most-commonly-used data serialization formats for web services. The core Serialization module provides a framework for adding specific serialization formats for other modules to use. {% endtrans %}</p>
   +<h2>{% trans %}What is Hypertext Application Language (HAL)?{% endtrans %}</h2>
   +<p>{% trans %}<a href="http://stateless.co/hal_specification.html">Hypertext Application Language (HAL)</a> is a serialization format that supports the linking required for hypermedia APIs, which are a style of Web API that uses URIs to identify resources and the <a href="http://wikipedia.org/wiki/Link_relation">link relations</a> between them, enabling API consumers to follow links to discover API functionality. The core HAL module provides HAL serialization to a JSON format.{% endtrans %}</p>
   +<h2>{% trans %}What is HTTP Basic authentication?{% endtrans %}</h2>
   

   HAL is mentioned in this introduction, but the HAL module isn't mentioned in the list of modules below?

3. +++ b/core/modules/help_topics/help_topics/core.web_services.html.twig
   @@ -0,0 +1,28 @@
   +  <dd>{% trans %}Exposes <em>entities</em> (such as content items, comments, and taxonomy terms) using a fully compliant implementation of the <a href="https://jsonapi.org">JSON:API Specification</a>.{% endtrans %}</dd>
   +  <dt>{% trans %}RESTful Web Services module{% endtrans %}</dt>
   +  <dd>{% trans %}Exposes entities and other resources using a <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> implementation.{% endtrans %}</dd>
   +  <dt>{% trans %}RDF module{% endtrans %}</dt>
   

   The description for REST is a bit tautological, mentioning which formats are available (like HAL) might help with that though.

Thanks for taking a look! Here's a new patch that tightens up and simplifies much of the text. I also moved all of the information about modules to the modules list, since (based on the previous review) the information about the HAL module wasn't easy to find in the previous version, even though it was mentioned.

I reviewed the patch, and found 1 more thing I would change to make it easier to read. See the interdiff.

Besides that I think this is ready to be RTBTC'ed.

Your change in #69 looks fine, and I tested the patch in #69 and it displays fine. So, I hereby RTBC your changes. Since you indicated in #69 that aside from the small change you made you think the patch is RTBC, I will go ahead and mark it RTBC. Thanks!

Thanks for the changes in #68 and #69, that's a lot easier to read.

Committed 4a8ea54 and pushed to 9.1.x. Thanks!