Add documentation to EntityRevision destination plugin

Initial patch attached.

This is intentionally including the 'custom_article_migration' migration in addition to the actual 'custom_article_revision_migration' instead of referring to the very similar example provided in EntityContentBase, see #2862662: Add documentation to EntityContentBase destination plugin

The reason for having a separate node migration example here is that:

• The example provided in EntityContentBase demonstrates the configuration keys. This revision example can be more minimalistic and only focus on the revision migration specific things. Therefore I wrote the patch so that we are only referring to the parent class EntityContentBase and saying that the configuration keys are documented there.
• The example provided in EntityContentBase does not include the revision id (vid for nodes). This was intentional because the purpose there was to only show the most simple node migration without revisions.

Cheers,
Markus

Added the relation to EntityContentBase destination plugin API doc improvements. These two patches should be preferably be committed at the same time.

Markus

Addressing both comments from #8.

Cheers,
Markus

Patch looks good ! Thanks for the patch @masipila . Marking RTBC.

Found still two typos, attached patch fixes them.

Last docs changes look like an improvement. LGTM.

I agree @heddn .

I'll change the source of the example to use embedded data source instead of EmtpySource so that this will be consistent with other examples.

As suggested by @masipila, replaced the EmptySource with an embedded data source.

+++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
@@ -14,6 +14,70 @@
+ * source:
+ *   plugin: d7_node

We need this source plugin in the example: https://api.drupal.org/api/drupal/core!modules!migrate!src!Plugin!migrat...

Here we go with embedded data source. I also incorporated the better labels for both examples from Jo's patch into this.

1. Made suggested change.
3. I see your point, @quietone, that would be a regular use case, but I think this version is still valid (and keeps it as simple as possible). In reality I think it is unlikely anyone would use the embedded_data plugin with this destination plugin, but it provides a simple example.

Re #19.3. Nid could and should be mapped with migration_lookup. Vid can not because this migration creates the revisions.

Working on this now.

And here we go. The revision example is now using migration_lookup to map the nid property.

Thanks for taking this on, @masipila! Looking quite good right out of the gate.

1. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -14,6 +14,91 @@
   + * Entity revision migration must always be a pair of the corresponding entity
   + * migration. For example, revisions of given node content type can be migrated
   

   Can we rephrase this first sentence? Something like "Entity revisions can only be migrated after the entity to which the revisions belong has been migrated." Also, "node content type" is redundant; we can just say "content type".

2. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -14,6 +14,91 @@
   + * In order to avoid revision ID conflicts, make sure that the entity migration
   + * also includes the revision ID.
   

   Can we elaborate on this at all? It sounds very ominous, but is not really explained.

3. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -14,6 +14,91 @@
   + * simplicity. The important part of both examples is the 'vid' property which
   

   We need a comma after the word "property".

4. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -14,6 +14,91 @@
   + * is the revision ID property for nodes.
   

   We can remove the word "property" here.

5. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -14,6 +14,91 @@
   + * Example for node migration:
   

   Should say "Example of a base node migration, which must run before the revision migration", or similar.

6. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -14,6 +14,91 @@
   + * Example for corresponding node revision migration:
   

   Maybe "Example of the corresponding revision migration, which must be run after the above migration"?

1-6: Done.

Nearly there!

1. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -17,19 +17,23 @@
   + * belong has been migrated. For example, revisions of given content type can be
   

   Nit: "...of a given content type..."

2. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -17,19 +17,23 @@
   + * also includes the revision ID. If the entity migration would not include the
   

   "...entity migration did not include the revision ID..."

3. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -17,19 +17,23 @@
   + * revision ID, the entity would get the next free revision ID (1 when migrating
   

   s/free/available.

4. +++ b/core/modules/migrate/src/Plugin/migrate/destination/EntityRevision.php
   @@ -17,19 +17,23 @@
   + * to a clean database). When the revisions are then migrated after the
   

   Should be "Then, when revisions are migrated..."

1-4: Done.

Thanks, @masipila. First-class work as always.

Thanks all, definitely looks like an improvement.