Add a DevHub manifest

[chrisvanpatten]

Not to merge until core Trac tickets are solved

• https://meta.trac.wordpress.org/ticket/4388
• https://meta.trac.wordpress.org/ticket/4244

Description

Based on today's WordPress #docs meeting (registration required), this PR adds a new manifest intended for consumption by DevHub.

This is intended to accomplish a few things:

• Leaves the legacy Gutenberg handbook unchanged
• Does not actually move any documentation files
• Moves designer/developer handbook content to the top level in DevHub
• Preserves the current location of the contributor handbook, now living as a section within the developer handbook

The plan from here would be to…

1. Re-build DevHub from this new manifest
2. Add wildcard redirects:

   https://wordpress.org/gutenberg/handbook/designers-developers/* → https://developer.wordpress.org/block-editor/*
   https://wordpress.org/gutenberg/handbook/contributors/* → https://developer.wordpress.org/block-editor/contributors/*
   

3. Disable manifest syncs at the legacy handbook
4. Move the contents of ./docs/designers-developers to the top level of ./docs and update toc.json accordingly (not doing this here so we can avoid unnecessarily complicating this PR)
5. Eventually, move manifest-devhub.json back to just manifest.json (once the above steps are working as expected) and consolidate down to a single build targeted at DevHub.

There may be a further desire to move the packages documentation up to the top level, but I'm avoiding that in this initial PR. I think it's worth seeing how this works first before we go further.

cc @Kenshino and @coffee2code

[chrisvanpatten]

We may also want to look at coordinating with the DevHub team to see if we can have some kind of global notice at developer.wordpress.org/block-editor saying something like

This documentation is for the version of the block editor that's bundled with WordPress core. To view the documentation for the latest version of the Gutenberg plugin, visit the Gutenberg GitHub repo.

[chrisvanpatten]

Another improvement here might be to allow passing --toc and --manifest flags to npm run docs:build so we can more easily have multiple TOCs building to multiple manifests.

That said, having multiple manifests is hopefully just temporary… so maybe not worth the energy :)

[mkaz]

Looks good! New manifest file is created and looks to be correct.

One minor thing, after running docs:build there appeared to be a white-space difference in the file
packages/core-data/README.md - you will probably need to commit that or you'll get an error

[oandregal]

With the changes here, the top-level TOC will be:

• Designers & Developers Handbook
• Key Concepts
• Developer Documentation *
• Data Module Reference *
• Packages *
• Components *
• Designer Documentation *
• Contributors Guide *

* means it contains subsections.

I'd change a few titles (the H1 in the proper README) and would move the reference docs to the bottom so it becomes:

• Gutenberg Handbook
• Key Concepts
• Developer Documentation *
• Designer Documentation *
• Contributor Documentation *
• Data Module Reference *
• Package Reference *
• Component Reference *

I'd like to see the other reference docs also moved to the top-level for coherence (Block API Reference, Filter Reference & Tutorials), but I'm also open to use this as a base and review the rest before launch.

[oandregal]

A few other logistic things:

• If we merge this, the current handbook TOC will also be modified. I guess we need to provide a toc-devhub.json and manifest-devhub.json for testing in DevHub as a first step (assuming the sync DevHub process is the same).

• Note that the "previous" / "next" links at the bottom of each page are generated from the manifest order (the current handbook has some issues). I've noticed that the manifest-devhub.json doesn't follow the toc.json section order either, so we need to fix that as well.

[chrisvanpatten]

@nosolosw The handbook and DevHub don't directly reference toc.json; it's just used as a way to map out how the manifest file should be built.

Because we're changing the output of the manifest generation script to create a manifest-devhub.json, the current manifest.json, and thus the legacy handbook, should remain totally unchanged and effectively frozen. We could provide a second TOC but that would assume we want to change the legacy manifest going forward, which I don't believe we actually want.

Once the redirects are in place, we'll be able to disable new builds on the legacy handbook site entirely so the manifest-devhub.json can be moved so manifest.json is again the canonical manifest, but only consumed by DevHub.

I didn't do a super deep comparison on toc.json and manifest-devhub.json but on a quick skim it seems to all be in the correct order. Is that not actually true? Are there any specific things that are out of order?

[chrisvanpatten]

(Also my hope is that we don't need to merge this in to actually test the DevHub sync; I wrote the PR this way with the assumption that we would only need to merge it in once we were confident this was the correct path forward.)

[oandregal]

The handbook and DevHub don't directly reference toc.json; it's just used as a way to map out how the manifest file should be built.

Ah, great, that simplifies things a bit (I actually thought the sidebar was created from it).

Also my hope is that we don't need to merge this in to actually test the DevHub sync;

Got it. Wasn't clear if we intended to merge this as it is.

I didn't do a super deep comparison on toc.json and manifest-devhub.json but on a quick skim it seems to all be in the correct order. Is that not actually true? Are there any specific things that are out of order?

The problem wasn't the discrepancy between toc and manifest as I hinted earlier, but pages that are generated automatically (data, packages, components): they are appended to the end of the manifest, so previous/next links will be wrong for their top-level sections and the last page of the handbook.

My old-self to the rescue 😅 #14794

[chrisvanpatten]

@nosolosw Oh shoot - those placeholder replacements aren’t working? That’s definitely a problem… I understand now. Hmm…

[oandregal]

As per this Slack convo we agreed to apply these changes and promote tutorials as a top-level section.

Pushed changes as individual commits so we can revert as necessary.

[coffee2code]

The Block Editor handbook on DevHub has been updated to reflect these latest changes.

A request and a suggestion:

• Please update the slug for "Block Editor Handbook" to "handbook" (instead of "designers-developers"). The page with that slug is treated as the front page of the handbook, and was previously used by the "Gutenberg Handbook" page until it was omitted from the DevHub-specific manifest in favor of having "Block Editor Handbook" be the front page. (DevHub currently has two versions of the page since I manually changed the slug for an instance of that page to ensure there was a front page.)
• A number of pages still use "Gutenberg" in their titles (but not their slugs), so "Gutenberg" could be omitted or changed to "Block Editor".

[oandregal]

Please update the slug for "Block Editor Handbook" to "handbook" (instead of "designers-developers")

Done at 740bd75 .

A number of pages still use "Gutenberg" in their titles (but not their slugs), so "Gutenberg" could be omitted or changed to "Block Editor".

I can prepare this change independently, as to have a good signal-to-noise balance in this PR.

[oandregal]

A number of pages still use "Gutenberg" in their titles (but not their slugs), so "Gutenberg" could be omitted or changed to "Block Editor".

Here's a WIP draft PR to address this #15411

AFAIK the current thinking of project members is that Gutenberg should be used for anything project-related and Block Editor is for the first product that came of Gutenberg. It's a transitional period, so things may be a bit confusing and intertwinned.

[oandregal]

This has been rebased with the latest changes done to the doc tool.

[oandregal]

Comment spun from this conversation with @coffee2code that I wanted to post here so people following this can participate.

Now that we're closer to the merge status, I'd like to expand on the plan to roll this:

• Re-build DevHub from this new manifest. It uses this manifest: https://raw.githubusercontent.com/WordPress/gutenberg/ADD/DEVHUB-MANIFEST/docs/manifest-devhub.json. Note that, when relative paths are working, content is to be pulled from this branch, not master (uppercase used for effect). See Scott comment.
• Publish existing DevHub content.
• Add wildcard redirects from the old handbook to DevHub.
• Merge this branch, but DO NOT DELETE IT. It will be still used to generate the DevHub content and bad things ™️ may happen if it no longer exists.
• Change DevHub to use the Gutenberg master branch instead: https://raw.githubusercontent.com/WordPress/gutenberg/MASTER/docs/manifest-devhub.json
• Now it's safe to delete this branch.
• We can now publicly talk and share about the DevHub migration, etc.

[coffee2code]

What's the overall ongoing plan for the handbook at https://wordpress.org/gutenberg/? That handbook uses a custom importer that differs from the one used on DevHub With the relative link changes applied to its manifest (manifest.json), the handbook content won't update unless I port relative path support to it separately.

Based on the latest comment, it looks like the entire handbook will soon redirect to the Block Editor handbook on DevHub, in which case I would be inclined to not make an effort to update the importer for the legacy Gutenberg handbook. (The legacy handbook will remain as you see it today until redirects are activated, at which point the handbook will no longer be accessible.)

[chrisvanpatten]

@coffee2code Yes, the plan is to fully deprecate the custom handbook and move into DevHub permanently! I agree; the old handbook should not be updated at this point, except to disable syncing and add redirects.

[oandregal]

This is ready! Let ship this to users :)

[oandregal]

Rebased this from master to force Travis to do its checks dance. For some reason, it didn't when I changed this PR from "draft" to "ready for review".

[oandregal]

Note that the current handbook sync has been disabled so this removal won't trigger any update (nor the other minor content updates).

[oandregal]

DO NOT DELETE THIS BRANCH YET. See.

[chrisvanpatten]

Thanks for seeing this through to the finish line @nosolosw — gold stars for you! ⭐️⭐️⭐️⭐️⭐️

[oandregal]

For reference: @aduth locked this branch from being deleted. We should remove the lock when we're ready to proceed with the next steps. I'll post here.

[coffee2code]

The manifest location for the new Block Editor handbook now uses the file in master and is now available to all visitors. The legacy handbook now redirects to the new handbook.

It should be safe to delete this branch. Then whenever it is so desired, a meta.trac ticket can be opened to re-point the handbook to a manifest file in a wp/{version} branch.

[gziolo]

See #15785. New Block Editor handbook should be using wp/5.2 branch which contains the snapshot of docs at the time WordPress 5.2 was released. Otherwise, it will cause more confusion.

[gziolo]

5. Eventually, move manifest-devhub.json back to just manifest.json (once the above steps are working as expected) and consolidate down to a single build targeted at DevHub.

We still keep two files in the repository but it looks like we only update manifest-devhub.json. Can we remove the other one?