Add "Connectors Reference" docs pages to LB4 docs

[dhmlau]

Description / Steps to reproduce / Feature proposal

When working on #1766, I realized that the docs pages under Connectors references are still very relevant, and also because we're still using the existing connectors.

I'd like to propose to copy these docs pages to LB4 docs.
@strongloop/loopback-maintainers, what do you think?

Acceptance Criteria

• Add the Connectors Reference including the subtree to LB4 docs.
  • memory connector
  • database connector
    • can we assume all will be working in LB4?
  • Other connectors
    • Are everything under this category works the same way in LB4? There's gap in email connector How email connector should work in Juggler-next #1980
  • community connectors

References:

• Sample of how it can be done: https://github.com/strongloop/loopback.io/blob/gh-pages/pages/en/lb3/Cloudant-connector.md.

See Reporting Issues for more tips on writing good issues

[bajtos]

I realized that the docs pages under Connectors references are still very relevant, and also because we're still using the existing connectors.

I'd like to propose to copy these docs pages to LB4 docs.

+1

There is more content in LB3 that's applicable to LB4 too. For example, the documentation for filter and where syntax, description of LDL (metadata used to define model and properties), etc.

[dhmlau]

FYI - @b-admike showed an example of how the content can be "copied" from the README of a repo to loopback.io: https://github.com/strongloop/loopback.io/blob/gh-pages/pages/en/lb3/Cloudant-connector.md.

[dhmlau]

For filter and where, we have a task for that already: #2527.

[dhmlau]

@bschrammIBM, thanks for taking up this task. I'm assigning it to you now. Thanks.

[bschrammIBM]

I moved the entire topic from LB3: https://loopback.io/doc/en/lb3/Connectors-reference.html to loopback-next repo and updated the sidebars and the headers.
The branch is connectors_from_lb3.
However, there is an error when building the site that needs to be resolved.
Here is the error message: Liquid Exception: Could not locate the included file 'readmes/loopback-connector-cassandra.md' in any of ["/Users/bschramm/loopback-next/sandbox/loopback.io/pages/en/lb4"]. Ensure it exists in one of those directories and, if it is a symlink, does not point outside your site source. in /_layouts/readme.html jekyll 3.7.4 | Error: Could not locate the included file 'readmes/loopback-connector-cassandra.md' in any of ["/Users/bschramm/loopback-next/sandbox/loopback.io/pages/en/lb4"]. Ensure it exists in one of those directories and, if it is a symlink, does not point outside your site source.

[bschrammIBM]

@b-admike Can you help trouble shoot this?

[bschrammIBM]

Also, I wanted to point out that you maybe should add a Connectors topics to the Key Concepts section.

[b-admike]

As discussed with @bschrammIBM

there are two options. either reference pages/en/lb3 in the permalink for the new connector docs you have moved to the monorepo or we need to copy the connector readmes in lb-next which I don't think is what we want because they're not lb4 specific docs i.e. they are not packages in the monorepo. I've pushed a new commit 8ebc181 after changing those permalinks and npm run build:site and npm t work fine now after rebasing.

[dhmlau]

Learning from @b-admike, the README.md files from the connectors repos were copied using scripts to https://github.com/strongloop/loopback.io/blob/gh-pages/pages/en/lb3/readmes.
I'm thinking that it's better to have a clean separation between lb3 and lb4 folders, i.e. the lb4 sidebars are pointing to files in the lb4 folder rather than the lb3 folder. In that case, when we need to remove lb3 folder for any reasons, it won't be causing missing links everywhere.

[dhmlau]

I'm good with either way.. to point to the lb3/readmes or to copy to lb4/readmes.

[bschrammIBM]

From @b-admike : "I think I have a solution but it'd probably involve a PR on loopback.io" and "There is another issue with symlinking @loopback/docs as part of the bootstrap process which would require modification on loopback-next repo too".
These edits cannot be seen in loopback 4 without a code modification to enable the links to the readmes.

[bschrammIBM]

Status update: The doc work for this issue is complete and resides in the connectors_from_lb3 branch. The changes are not reflected in the build for the doc site due to the issues described by Biniam above.

[dhmlau]

@b-admike was helping to land the PR but was running into some build issues. That's why this task is blocked.

[hacksparrow]

These two PRs need to be landed to close this issue.

• feat: add Connector docs to LB4 docs loopback.io#863
• feat: add Connector docs to LB4 docs #3481

[hacksparrow]

The PRs have landed. Closing this issue.