[WIP] Pull LoopBack 4 doc updates from loopback-next #643

b-admike · 2018-03-09T18:32:08Z

Connect to loopbackio/loopback-next#843. This script copies over the doc files for LoopBack 4 content into this repo, and reverts some linking changes made in loopback-next in order to render it properly when Jekyll is run. Mad credits to @rmg for essentially writing the script! The script is intended to demonstrate how to achieve the proposal in the spike, so it would probably need to be modified if we are to use this approach.

EDIT The script now utilizes @loopback/docs to pull in the latest changes from loopback-next for LoopBack 4 docs and jekyll-relative-links plugin to handle .md links (with one exception). It also provides a Travis config to deploy to GitHub Pages whenever there are new changes.

rmg · 2018-03-09T19:04:19Z

Your update-lb4-docs.sh needs a shebang at the top (#!/bin/bash) to ensure that it is executed with the correct interpreter instead of relying on /bin/sh being the default.

rmg · 2018-03-09T19:24:39Z

update-lb4-docs.sh

+   | tar --strip-components 1 -C $tmp -xzf- '*.md'
+cp -R $tmp/packages $target/readmes/$repo
+#rename relative link extensions from md to html
+sed -E -i 's/\(([^(]+)\.md/(\1.html)/g' $tmp/docs/*.md


You have:

s/$([^(]+)\.md/(\1.html)/g

It should be this:

s/\(([^(]+)\.md$/(\1.html)/g

You need to match the closing ) literal otherwise it doesn't get replaced by the ) literal in the replacement and you end up with double )) on the output - and also incorrectly matching:
(index.md other stuff) -> (index.html) other stuff)

Good catch. Actually I wanted to include the cases where .md is followed by # and left out the literal match for ). I will remove it from the replacement as well.

bschrammIBM

lgtm

shimks

LGTM, but one comment

shimks · 2018-03-12T18:59:31Z

update-lb4-docs.sh

+curl -L https://github.com/$ORG/$REPO/archive/$COMMIT.tar.gz | tar --strip-components 1 -C "$DOCS" --wildcards \
+-xzf- "$ARCHIVE_NAME/docs/*.md" "$ARCHIVE_NAME/packages/*.md" "$ARCHIVE_NAME/docs/*.png"
+
+# cp -R $DOCS/packages $DOCS/readmes/$REPO


Was this meant to be commented out?

virkt25 · 2018-03-12T19:39:00Z

update-lb4-docs.sh

+ORG=strongloop
+REPO=loopback-next
+DOCS=./pages/en/lb4
+COMMIT=893d68547766fc41d8bca82425645416e357d052


Is this meant to be hard-coded?

Good catch; it's supposed to be master.

virkt25 · 2018-03-12T19:39:53Z

update-lb4-docs.sh

+curl -L https://github.com/$ORG/$REPO/archive/$COMMIT.tar.gz | tar --strip-components 1 -C "$DOCS" --wildcards \
+-xzf- "$ARCHIVE_NAME/docs/*.md" "$ARCHIVE_NAME/packages/*.md" "$ARCHIVE_NAME/docs/*.png"
+
+# cp -R $DOCS/packages $DOCS/readmes/$REPO


raymondfeng · 2018-03-12T19:53:56Z

Jenkinsfile

  }
  stage('download updates') {
    sh './update-readmes.sh'
-    sh './update-v4-readmes.sh'


We probably should keep sh './update-v4-readmes.sh' here as it's used to pull in README files. Even after we move docs to the monorepo, we might continue to pull in README files.

raymondfeng · 2018-03-12T19:54:26Z

update-lb4-docs.sh

+mkdir -p $DOCS
+# pull down all the markdown files (reserving dir structure)
+# given the GitHub ORG, REPO, and COMMIT
+curl -L https://github.com/$ORG/$REPO/archive/$COMMIT.tar.gz | tar --strip-components 1 -C "$DOCS" --wildcards \


At some point, it's probably better to switch to npm install

virkt25 · 2018-03-14T16:56:45Z

update-lb4-docs.sh

+# -xzvf- "$ARCHIVE_NAME/docs/*.md" "$ARCHIVE_NAME/packages/*.md"
+# "$ARCHIVE_NAME/docs/*.png"
+npm i @loopback/docs --prefix $DOCS
+mv $DOCS/node_modules/@loopback/docs $DOCS/monorepo-docs


Is /monorepo-docs needed? Or can we just move the docs fo $DOCS?

The site/* should be copied into pages/en/lb4/.

I was just using it as a placeholder, before we implement changes that override the current doc contents, but yeah it should be site/*.

raymondfeng · 2018-03-14T17:12:54Z

I just published @loopback/docs@0.1.2, which has all related files under site directory.

raymondfeng · 2018-03-14T17:31:39Z

update-lb4-docs.sh

+#curl -L https://github.com/$ORG/$REPO/archive/$BRANCH.tar.gz | tar --strip-components 1 -C "$DOCS" --wildcards \
+# -xzvf- "$ARCHIVE_NAME/docs/*.md" "$ARCHIVE_NAME/packages/*.md"
+# "$ARCHIVE_NAME/docs/*.png"
+npm i @loopback/docs --prefix $DOCS


I think it can be further simplified if we add @loopback/docs as a dependency in package.json of loopback.io. This way, npm install at the root level will pull in node_modules/@loopback/docs and we can add a post-install script to copy them to the right place.
_

I talked to @rmg and if we aim to do that, then we should probably introduce Travis to this repo since the Jenkins pipeline is

running directly on the Jenkins master and that server doesn't have any external executors

and doesn't have node/npm installed. It would be a hassle to install them there. Also,

all GitHub Pages does is run Jekyll and upload the generated _site directory (or whatever it is..) to S3

raymondfeng · 2018-03-15T15:58:54Z

update-lb4-docs.js

+const destImages = path.resolve(__dirname, 'images', 'lb4');
+
+function copyDocs(src, dest) {
+    try {


IIRC, we should use two spaces for indentation.

rmg · 2018-03-23T16:57:12Z

_layouts/page.html

+   {% if site.lb4_editme_path and page.layout != 'readme' and page.sidebar == 'lb4_sidebar' %}
+       {% assign edit_url =  page.url | remove: "doc/en/lb4" | remove: ".html" | append: ".md" | prepend: site.lb4_editme_path %}
+       <a target="_blank" href="https://github.com/{{edit_url}}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit this page</a>
+  {% endif %}


wrong indentation?

rmg · 2018-03-23T16:58:51Z

Jenkinsfile


 env.CHANGE_BRANCH = env.CHANGE_BRANCH ?: env.BRANCH_NAME

+


Looks like a random whitespace change was accidentally left in.

virkt25 · 2018-03-23T17:19:17Z

.travis.yml

+    - npm test
+  email: slnode@ca.ibm.com
+  name: StrongLoop Bot
+


Think there's some extra empty space here.

rmg · 2018-03-23T18:17:46Z

Travis has been configured

b-admike · 2018-03-26T18:27:25Z

Unfortunately, we can't use custom commit messages for the commits made by Travis on successful builds, but the feature might come soon https://github.com/travis-ci/travis-ci/issues/9287.

Add a script to copy over loopback-next docs using @loopback/docs. Add Travis config to pick up the changes and deploy to GitHub Pages upon a successful build. Run README update scripts from Travis as well and remove Jenkinsfile which did the same thing with Jenkins.

b-admike requested a review from bschrammIBM as a code owner March 9, 2018 18:32

b-admike added the needs-priority label Mar 9, 2018

b-admike changed the title ~~pull lb4 doc updates from loopback-next~~ Pull LoopBack 4 doc updates from loopback-next Mar 9, 2018

b-admike force-pushed the pull-monorepo-docs branch 5 times, most recently from 5e74638 to 6f23a25 Compare March 9, 2018 19:00

rmg reviewed Mar 9, 2018

View reviewed changes

b-admike force-pushed the pull-monorepo-docs branch from 5b86ea9 to 2287b46 Compare March 9, 2018 20:10

bschrammIBM approved these changes Mar 9, 2018

View reviewed changes

b-admike changed the title ~~Pull LoopBack 4 doc updates from loopback-next~~ [WIP] Pull LoopBack 4 doc updates from loopback-next Mar 9, 2018

b-admike force-pushed the pull-monorepo-docs branch 2 times, most recently from 4c54f77 to 9931ef0 Compare March 12, 2018 16:21

kjdelisle force-pushed the pull-monorepo-docs branch from 9931ef0 to 482420b Compare March 12, 2018 17:00

shimks approved these changes Mar 12, 2018

View reviewed changes

virkt25 reviewed Mar 12, 2018

View reviewed changes

b-admike force-pushed the pull-monorepo-docs branch 3 times, most recently from 6fb79d5 to eee1484 Compare March 12, 2018 19:52

raymondfeng requested changes Mar 12, 2018

View reviewed changes

kjdelisle force-pushed the pull-monorepo-docs branch from 24c7c8c to 5d44653 Compare March 12, 2018 20:06

b-admike force-pushed the pull-monorepo-docs branch from f7de9ec to 678a0d2 Compare March 12, 2018 20:14

shimks approved these changes Mar 12, 2018

View reviewed changes

b-admike force-pushed the pull-monorepo-docs branch from 678a0d2 to 73d54a1 Compare March 12, 2018 20:52

virkt25 reviewed Mar 14, 2018

View reviewed changes

raymondfeng reviewed Mar 14, 2018

View reviewed changes

raymondfeng reviewed Mar 15, 2018

View reviewed changes

b-admike force-pushed the pull-monorepo-docs branch from 19493fd to aae94cf Compare March 20, 2018 19:23

rmg reviewed Mar 23, 2018

View reviewed changes

virkt25 reviewed Mar 23, 2018

View reviewed changes

virkt25 approved these changes Mar 23, 2018

View reviewed changes

b-admike force-pushed the pull-monorepo-docs branch 2 times, most recently from 37ab270 to a563306 Compare March 23, 2018 20:26

raymondfeng approved these changes Mar 23, 2018

View reviewed changes

b-admike force-pushed the pull-monorepo-docs branch 12 times, most recently from ac9f169 to 2f5382f Compare March 26, 2018 18:19

b-admike force-pushed the pull-monorepo-docs branch 3 times, most recently from 5f23fcb to 5daa9ae Compare March 26, 2018 18:59

b-admike force-pushed the pull-monorepo-docs branch from e8f7b01 to 09d4ef6 Compare March 26, 2018 19:41

b-admike merged commit fa3608c into gh-pages Mar 26, 2018

b-admike deleted the pull-monorepo-docs branch March 26, 2018 19:41

b-admike restored the pull-monorepo-docs branch March 26, 2018 19:53

[WIP] Pull LoopBack 4 doc updates from loopback-next #643

[WIP] Pull LoopBack 4 doc updates from loopback-next #643

Uh oh!

Conversation

b-admike commented Mar 9, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rmg commented Mar 9, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bschrammIBM left a comment

Choose a reason for hiding this comment

Uh oh!

shimks left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raymondfeng commented Mar 14, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rmg commented Mar 23, 2018

Uh oh!

b-admike commented Mar 26, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

b-admike commented Mar 9, 2018 •

edited

Loading