Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "Connectors Reference" docs pages to LB4 docs #2598

Closed
dhmlau opened this issue Mar 15, 2019 · 15 comments

Comments

@dhmlau
Copy link
Contributor

commented Mar 15, 2019

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 #1980
    • community connectors

References:

See Reporting Issues for more tips on writing good issues

@dhmlau dhmlau added the Docs label Mar 15, 2019

@bajtos

This comment has been minimized.

Copy link
Member

commented Mar 19, 2019

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

This comment has been minimized.

Copy link
Contributor Author

commented Mar 19, 2019

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 dhmlau added the 2019Q2 label Mar 19, 2019

@dhmlau

This comment has been minimized.

Copy link
Contributor Author

commented Mar 19, 2019

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

@dhmlau dhmlau referenced this issue Apr 4, 2019
7 of 7 tasks complete
@dhmlau

This comment has been minimized.

Copy link
Contributor Author

commented Apr 5, 2019

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

@bschrammIBM

This comment has been minimized.

Copy link
Contributor

commented Apr 17, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Apr 17, 2019

@b-admike Can you help trouble shoot this?

@bschrammIBM

This comment has been minimized.

Copy link
Contributor

commented Apr 17, 2019

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

@dhmlau dhmlau added the p2 label Apr 18, 2019

@b-admike

This comment has been minimized.

Copy link
Member

commented Apr 19, 2019

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

This comment has been minimized.

Copy link
Contributor Author

commented Apr 23, 2019

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

This comment has been minimized.

Copy link
Contributor Author

commented Apr 23, 2019

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

@bschrammIBM

This comment has been minimized.

Copy link
Contributor

commented May 7, 2019

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

This comment has been minimized.

Copy link
Contributor

commented May 8, 2019

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 dhmlau added 2019Q3 p1 blocked and removed 2019Q2 p2 labels Jun 11, 2019

@dhmlau

This comment has been minimized.

Copy link
Contributor Author

commented Jun 11, 2019

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

@hacksparrow

This comment has been minimized.

Copy link
Member

commented Jul 31, 2019

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

@hacksparrow

This comment has been minimized.

Copy link
Member

commented Jul 31, 2019

The PRs have landed. Closing this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.