fix: make sure generated readmes for lb4 have correct links

[raymondfeng]

This is a follow-up to #588.

The PR introduces page.file to customize the location of the README file.

The update-v4-readmes.sh script now downloads README files into
pages/en/lb4/readmes/loopback-next/packages/<pkg>/README.md and the readme.html Jekyll template honors page.file setting.

For example:

---
lang: en
title: 'Creating decorators'
keywords: LoopBack 4.0, LoopBack 4
layout: readme
source: loopback-next
file: packages/metadata/README.md
tags:
sidebar: lb4_sidebar
permalink: /doc/en/lb4/Creating-decorators.html
summary: A tutorial to use `@loopback/metadata` module to create new decorators
---

The template will use loopback-next/packages/metadata/README.md as the file location and https://github.com/strongloop/loopback-next/blob/master/packages/metadata/README.md as the link.

[kjdelisle]

Does this need to be altered to include all of the packages? It seems like we're only pointing at metadata with this setup.

[raymondfeng]

For LB4, we only pull in README for metadata at this moment. This is the place you can add more readmes to be imported.

[bschrammIBM]

You are probably aware of this, but the Commit Linter failed.

[bajtos]

I am not sure if it's a good idea to support both "npm module" and "github branch" modes. What are the rules/guidelines for deciding what source to use when? Could you please describe them in the comment inside update-v4-readmes.sh?

Also, have you verified that "npm module" downloads actually work - that they put the contents to a right place and that the generated link is pointing to the right npm package?

[bajtos]

I think this will not work because we are not publishing loopback-next to npmjs.org. Unless I am missing something?

[raymondfeng]

We only pull from npmjs if the module field (last one) is specified.

[bajtos]

I see. Could you please enhance the comments to explain what is each example showing?

[bajtos]

What are the rules/guidelines for deciding what source to use when?

Maybe we should use the following rule?

• For public packages published to npmjs.org, we should download the latest published version, because that's the version what our users are going to use and see after running npm install.
• For private packages (typically examples), we should download the latest version from master, because that's the version our users will get after running lb4 example.

Thoughts?

[raymondfeng]

I am not sure if it's a good idea to support both "npm module" and "github branch" modes. What are the rules/guidelines for deciding what source to use when? Could you please describe them in the comment inside update-v4-readmes.sh?

I didn't invent that. The PR follows what we do for LB v3.

Also, have you verified that "npm module" downloads actually work - that they put the contents to a right place and that the generated link is pointing to the right npm package?

Yes. I did. See the following comments in the script:

The following is a 5 column list of org, repo, branch, file, and module.
# - If the module is specified, the README for that project will be
#   pulled from npmjs.org instead and will reflect the latest release.
#   For scoped packages such as `@loopback/metadata`,  the `/` needs to
#   be encoded as `%2f`. For example `@loopback%2fmetadata`.

[bajtos]

The code changes looks reasonable, I don't see any obvious problem.

I think we should rethink the way how we are mirroring READMEs, but I guess that's beyond the scope of this pull request.