docs: move documentation into monorepo #1100

kjdelisle · 2018-03-07T22:35:10Z

Migrate the existing lb4 files under the docs folder of the monorepo

connected to #988

Checklist

npm test passes on your machine
New tests added or existing tests modified to cover all changes
Code conforms with the style guide
Related API Documentation was updated
Affected artifact templates in packages/cli were updated
Affected example projects in packages/example-* were updated

virkt25 · 2018-03-08T01:46:28Z

I would like to preserve language folders under docs, so these files should be in docs/en/
Do we have the necessary infrastructure in place for changes made to docs to be propagated to loopback.io automatically? (I'm aware of the scripts we have, but I thought there were still issues to work out?).

raymondfeng · 2018-03-08T17:50:20Z

Maybe a simple way to propagate docs into loopback.io repo is git submodule

kjdelisle · 2018-03-08T19:01:21Z

I would like to preserve language folders under docs, so these files should be in docs/en/

We already write the docs in English first and then have them translated after the fact. Is that not something we can do in the loopback.io repository? Technically, our doc structure is pages/en/lb4/*, so doing that would ruin the drop-in compatibility of this approach.

By using the docs folder in this way, we can rework the doc site to pull from the docs folder underneath and that would be all we'd need to do. Translation could then subsequently target the pages/en/lb4/* folders and subfolders to find all translatable content.

Do we have the necessary infrastructure in place for changes made to docs to be propagated to loopback.io automatically? (I'm aware of the scripts we have, but I thought there were still issues to work out?).

Gotta start somewhere!

virkt25 · 2018-03-08T19:53:41Z

I just figured it might be easier for the translations to live in the same place as well.

@raymondfeng I remember looking at git submodules as an option some time ago and it just requires everyone checking out the monorepo to be aware of those commands and running them ... but maybe all we need to do it automate it under the bootstrap script. The PR opens under loopback.io still though right? Is that what we want?

shimks

There's some missed html to md changes

shimks · 2018-03-08T20:00:03Z

docs/Concepts.md

+- [**Dependency Injection**](Dependency-injection.md): Technique that separates the construction of dependencies of a class or function from its behavior, to keep the code loosely coupled.
+- [**Controller**](Controllers.md): Class that implements operations defined by application’s REST API. It implements an application’s business logic and acts as a bridge between the HTTP/REST API and domain/database models. A Controller operates only on processed input and abstractions of backend services / databases.
+- [**Route**](Routes.md): Mapping between your API specification and an Operation (JavaScript implementation). It tells LoopBack which function to invoke() given an HTTP request.
+- [**Sequence**](Sequence.md): A stateless grouping of [Actions](Sequence.html#actions) that control how a Server responds to requests.


Sequence.md

shimks · 2018-03-08T20:00:18Z

docs/Concepts.md

+- [**Repository**](Repositories.md): Type of Service that represents a collection of data within a DataSource.
+- [**Decorator**](Decorators.md): Enables you to annotate or modify your class declarations and members with metadata.
+- **Component**: A package that bundles one or more Loopback extensions.
+  - See [Using components](Using-components.html) and [Creating components](Creating-components.md) for more information.


Using-components.md

shimks · 2018-03-08T20:00:53Z

docs/Defining-and-validating-the-API.md

+});
+```
+
+See [Validate your OpenAPI specification](Testing-your-application.html#validate-your-openapi-specification) from [Testing your application](Testing-your-application.md) for more details.


shimks · 2018-03-08T20:01:11Z

docs/Examples-and-tutorials.md

+  rpc-server: A basic RPC server using a made-up protocol.
+```
+
+Please follow the instructions in [Install LoopBack4 CLI](Getting-started.html#install-loopback-4-cli) if you don't have `lb4` installed yet.


shimks · 2018-03-08T20:01:27Z

docs/LoopBack-3.x.md

+summary:
+---
+
+LoopBack 4 is the next generation of the LoopBack framework, with a completely rewritten core foundation and significantly improved programming model. If you're an existing LoopBack user, read [Crafting LoopBack 4](Crafting-LoopBack-4.html) to understand the motivations, strategy, and innovations behind this exciting new version.


shimks · 2018-03-08T20:05:02Z

docs/Creating-components.md

+
+The idiomatic solution has two parts:
+
+ 1. The component should define and bind a new [Sequence action](Sequence.html#actions), for example `authentication.actions.authenticate`:


shimks · 2018-03-08T20:05:14Z

docs/Creating-components.md

+
+More often than not, the component may want to offer different value providers depending on the configuration. For example, a component providing an email API may offer different transports (stub, SMTP, and so on).
+
+Components should use constructor-level [Dependency Injection](Context.html#dependency-injection) to receive the configuration from the application.


shimks · 2018-03-08T20:05:30Z

docs/Decorators.md

+  Model decorator is a Class decorator.
+  In LoopBack 4, we inherit the model definition format from LoopBack 3,
+  you can find it in [Model definition JSON file](../lb3/Model-definition-JSON-file.md).
+  For usage examples, see [Define Models](Repositories.html#define-models)


shimks · 2018-03-08T20:05:44Z

docs/Decorators.md

+  The property decorator defines metadata for a property on a Model definition.
+  The format of property definitions can be found in [Property definitions](../lb2/Model-definition-JSON-file.html#properties)
+
+  For usage examples, see [Define Models](Repositories.html#define-models)


shimks · 2018-03-08T20:05:53Z

docs/Decorators.md

+  This decorator either injects an existing repository or creates a repository
+  from a model and a datasource.
+
+  The injection example can be found in [Repository#controller-configuration](Repositories.html#controller-configuration)


shimks · 2018-03-08T20:12:00Z

docs/Model.md

+The model decorator can be used without any additional parameters, or can be
+passed in a
+<!-- should be replaced with a lb4 example when possible -->
+[ModelDefinitionSyntax](https://loopback.io/doc/en/lb3/Model-definition-JSON-file.html)


Not really a part of the issue you're addressing, but can we change the link to (../lb3/Model-definition-JSON-file.html) so that it visits the local page?

We already spoke about it, but I'm commenting for posterity.

The lb3 folder won't be present in the monorepo, so the links need to be absolute so that they work both from the repository directly, and from loopback.io.

b-admike

👏

shimks

There's still some links that use relative paths.

shimks · 2018-03-09T17:32:55Z

docs/Extending-LoopBack-4.md

+
+The diagram below shows how the Context manages services and their dependencies.
+
+![loopback-ioc](/images/lb4/loopback-ioc.png)


Relative path

shimks · 2018-03-09T17:33:03Z

docs/Extending-LoopBack-4.md

+
+2. Services can be organized as extension points and extensions. For example, to allow multiple authentication strategies, the `authentication` component can define an extension point as `authentication-manager` and various authentication strategies such as user/password, LDAP, oAuth2 can be contributed to the extension point as extensions. The relation will look like:
+
+![loopback-extension](/images/lb4/loopback-extension.png)


Relative path

shimks · 2018-03-09T17:33:09Z

docs/Extending-LoopBack-4.md

+
+The interaction between the application context and `UserManagement` component is illustrated below:
+
+![loopback-component](/images/lb4/loopback-component.png)


Relative path

jannyHou · 2018-03-09T21:48:40Z

A question may not directly related to this PR, but could affects the PRs afterwards:

By "propagating docs", does it mean we always synchronize the docs in loopback-next/docs and loopback.io bi-directions(loopback.io <--> loopback-next/docs) or just one direction(loopback-next/docs --> loopback.io)?

virkt25 · 2018-03-11T04:03:35Z

@jannyHou It should be a one way sync, loopback-next/docs => loopback.io.

Gotta start somewhere!

I agree! And this is a great effort. I guess my concern is along the lines of till we have the synchronization in place, where should the docs changes be made (here or in loopback.io).

Migrate the existing lb4 files under the docs folder of the monorepo

kjdelisle · 2018-03-12T17:59:51Z

By "propagating docs", does it mean we always synchronize the docs in loopback-next/docs and loopback.io bi-directions(loopback.io <--> loopback-next/docs) or just one direction(loopback-next/docs --> loopback.io)?

Monodirectional, from this repository to loopback.io.

kjdelisle requested review from bajtos and raymondfeng as code owners March 7, 2018 22:35

kjdelisle added the needs-priority label Mar 7, 2018

kjdelisle force-pushed the move-docs-into-monorepo branch from 18822a5 to 30cea89 Compare March 7, 2018 22:35

kjdelisle force-pushed the move-docs-into-monorepo branch 2 times, most recently from 1885fcd to 7974746 Compare March 8, 2018 19:44

shimks reviewed Mar 8, 2018

View reviewed changes

kjdelisle force-pushed the move-docs-into-monorepo branch from bef12c7 to 144d226 Compare March 9, 2018 16:47

b-admike approved these changes Mar 9, 2018

View reviewed changes

shimks suggested changes Mar 9, 2018

View reviewed changes

shimks approved these changes Mar 9, 2018

View reviewed changes

kjdelisle force-pushed the move-docs-into-monorepo branch 2 times, most recently from 893d685 to b08cefc Compare March 12, 2018 17:57

docs: move documentation into monorepo

b08cefc

Migrate the existing lb4 files under the docs folder of the monorepo

kjdelisle merged commit e2be3a8 into master Mar 12, 2018

kjdelisle removed the needs-priority label Mar 12, 2018

kjdelisle deleted the move-docs-into-monorepo branch March 12, 2018 18:44

b-admike mentioned this pull request Mar 16, 2018

Spike: Move documentation to monorepo #843

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: move documentation into monorepo #1100

docs: move documentation into monorepo #1100

kjdelisle commented Mar 7, 2018 •

edited

Loading

virkt25 commented Mar 8, 2018

raymondfeng commented Mar 8, 2018

kjdelisle commented Mar 8, 2018

virkt25 commented Mar 8, 2018

shimks left a comment

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

shimks Mar 8, 2018

kjdelisle Mar 9, 2018

b-admike left a comment

shimks left a comment

shimks Mar 9, 2018

shimks Mar 9, 2018

shimks Mar 9, 2018

jannyHou commented Mar 9, 2018

virkt25 commented Mar 11, 2018

kjdelisle commented Mar 12, 2018


		The idiomatic solution has two parts:

		1. The component should define and bind a new [Sequence action](Sequence.html#actions), for example `authentication.actions.authenticate`:


		More often than not, the component may want to offer different value providers depending on the configuration. For example, a component providing an email API may offer different transports (stub, SMTP, and so on).

		Components should use constructor-level [Dependency Injection](Context.html#dependency-injection) to receive the configuration from the application.


		The diagram below shows how the Context manages services and their dependencies.

		![loopback-ioc](/images/lb4/loopback-ioc.png)


		2. Services can be organized as extension points and extensions. For example, to allow multiple authentication strategies, the `authentication` component can define an extension point as `authentication-manager` and various authentication strategies such as user/password, LDAP, oAuth2 can be contributed to the extension point as extensions. The relation will look like:

		![loopback-extension](/images/lb4/loopback-extension.png)


		The interaction between the application context and `UserManagement` component is illustrated below:

		![loopback-component](/images/lb4/loopback-component.png)

docs: move documentation into monorepo #1100

docs: move documentation into monorepo #1100

Conversation

kjdelisle commented Mar 7, 2018 • edited Loading

Checklist

virkt25 commented Mar 8, 2018

raymondfeng commented Mar 8, 2018

kjdelisle commented Mar 8, 2018

virkt25 commented Mar 8, 2018

shimks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b-admike left a comment

Choose a reason for hiding this comment

shimks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jannyHou commented Mar 9, 2018

virkt25 commented Mar 11, 2018

kjdelisle commented Mar 12, 2018

kjdelisle commented Mar 7, 2018 •

edited

Loading