Update manifest generation to use relative urls

[oandregal]

NOT TO MERGE UNTIL CORE CHANGES ARE ADDRESSED

Fixes #14303
Related core ticket: https://meta.trac.wordpress.org/ticket/4244

[youknowriad]

Thinking if this should be just docs/readme.md (relative to the root of the repository instead of being relative to the file). I wonder which one is simpler for the importer. cc @dd32

[dd32]

The docs importer only accepts an absolute URI here. https://meta.trac.wordpress.org/browser/sites/trunk/wordpress.org/public_html/wp-content/themes/pub/gutenberg/inc/docs-importer.php#L25

Adding the functionality to support a relative URL is doable if needed.

[oandregal]

Note that there is a related issue to migrate contents to DevHub https://meta.trac.wordpress.org/ticket/4388

[youknowriad]

@nosolosw Do you think we can provide the meta patch in parallel to the work done here? that way we merge both at the same time?

[oandregal]

Rebased from master, as there were notable and conflicting changes to the docs tool lately,

[coffee2code]

Can I get some clarification on how relative paths were envisioned to work? Currently, two manifests are utilized (the second via #15254).

manifest.json has:

• Location: https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/manifest.json
• OLD markdown_source example:
  https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/key-concepts.md
• NEW markdown_source example:
  ../docs/designers-developers/key-concepts.md

manifest-devhub.json has:

• Location: https://raw.githubusercontent.com/WordPress/gutenberg/add/devhub-manifest/docs/manifest-devhub.json
• OLD markdown_source example:
  https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/key-concepts.md
• NEW markdown_source example:
  ../docs/designers-developers/key-concepts.md

In both cases, it appears .. represents https://raw.githubusercontent.com/WordPress/gutenberg/master, assuming both manifests are meant to point to the same file (as they did before this change).

My question: for manifest-devhub.json, should the relative path resolve to:

1. https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/key-concepts.md

or should it resolve to:

2. https://raw.githubusercontent.com/WordPress/gutenberg/add/devhub-manifest/docs/designers-developers/key-concepts.md

Bear in mind, the path that relative paths are relative to is the location for the manifest. So my belief is that (2) is the intent. This allows for a manifest in a branch to easily reference files relative to its own branch. The markdown_source values of designers-developers/key-concepts.md, /designers-developers/key-concepts.md, and ../docs/designers-developers/key-concepts.md would all be equivalent and resolve to (2). (I have this implemented locally.)

However, if you expect the path to be relative to the repo root, then I believe you'd have to use a markdown_source value like master/docs/designers-developers/key-concepts.md to refer to the master branch's version of a file, or something like add/devhub-manifest/docs/designers-developers/key-concepts.md to refer to the version of that file in a branch/PR.

(I'm running under the assumption that these or future manifests may want to refer to non-master versions of files.)

[oandregal]

Bear in mind, the path that relative paths are relative to is the location for the manifest. So my belief is that (2) is the intent. This allows for a manifest in a branch to easily reference files relative to its own branch.

Yep. The idea is to be able to pinpoint the handbook content to a specific commit hash (branch, tag, etc) - see conversation.

[coffee2code]

So then as far as my question goes, the relative link of ../docs/designers-developers/key-concepts.md currently found in manifest-devhub.json should expand to refer to https://raw.githubusercontent.com/WordPress/gutenberg/add/devhub-manifest/docs/designers-developers/key-concepts.md and not master, correct?

[coffee2code]

Ah, I see the answer to my question in a comment on #15254, and that my presumption of the relative link pointing to the manifest's branch is correct.

[oandregal]

This can be closed. It is superseded by #15254 which includes relative paths support.

Current handbook sync has been disabled and relative paths not implemented for this. See https://meta.trac.wordpress.org/ticket/4244#comment:7