docs: improve the structure of "Usage scenarios" (how-to guides) sidebar

[bajtos]

At the moment, "Usage scenarios" sidebar is a bit messy:

Some pages are nested under subcategories like "Access databases" and "Deployment", others are at top level ("Using Express Middleware", "Running cron jobs", etc.)

Let's reorganize the how to guides along different usage scenarios they belong to: Build REST APIs, Access databases, Access existing services, Authentication/authorization, Cloud native, Dependency Injection & IoC, etc.

• Keep "Usage scenarios" ("How-to guides") at the first level.
• All second level items should be groups - Build REST APIs, Access Databases, etc.
• Individual documentation pages are listed at third (or possibly fourth) level.

Use Deployment as the example to follow.

See also:

• Improve the structure of "Behind the scenes" sidebar docs: improve the structure of "Behind the scenes" sidebar + find a better name #5776

This story is a part of #5113 Documentation improvements 2020Q3

Acceptance criteria

• Keep "Usage scenarios" ("How-to guides") at the first level.
• All second level items should be groups - Build REST APIs, Access Databases, etc.
• Individual documentation pages are listed at third (or possibly fourth) level.

Use Deployment as the example to follow.

[jannyHou]

A proposal of the new layout:

Building REST APIs

• Booting and mounting a LoopBack 3 application
• Creating CRUD REST APIs from a model
• Customizing how OpenAPI spec is served
• Dynamically adding models, repositories, and controllers
• Self-hosted REST API explorer
• Serving static files
• Uploading and downloading files
• Using express middleware

Creating Other Forms of APIs

• Exposing GraphQL APIs

Accessing Database

• Database migrations
• Using database transactions
• Working with data

Using TypeORM

• How to use TypeORM with LoopBack

Validation

• Validation in REST Layer
• Validation in the Controller, Repository and Service Layer
• Validation in ORM Layer

Security

• Authentication
• Authorization

Deployment

• Enabling HTTPS
• Deploying to IBM cloud
• Deploying to Kubernetes on IBM cloud
• Deploying with pm2 and nginx
• Developing and Deploying LoopBack Applications with Appsody

Accessing services

• Calling other services

Running and debugging apps

• Setting debug strings
• Using strong-error-handler
• Running cron jobs

Metrics

• Health check
• Metrics for Prometheus

---

Compare with the current layout, see picture in #5777 (comment)

cc @strongloop/loopback-maintainers PTAL and share your feedback, appreciate it :)
After we agree on the layout and titles, I will create a PR for it.

[raymondfeng]

A proposal of the new layout:

Building REST APIs

• Creating CRUD REST APIs from a model
• Customizing how OpenAPI spec is served
• Dynamically adding models, repositories, and controllers
• Self-hosted REST API explorer
• Serving static files
• Uploading and downloading files
• Using express middleware
• Booting and mounting a LoopBack 3 application

Creating Other Forms of APIs

• Exposing GraphQL APIs

Accessing Database

• Working with data

• Using database transactions

• Database migrations

• Using TypeORM

  • How to use TypeORM with LoopBack

Accessing services

• Calling other services

Validation

• Validation in REST Layer
• Validation in the Controller, Repository and Service Layer
• Validation in ORM Layer

Security

• Authentication
• Authorization

Deployment

• Enabling HTTPS
• Deploying to IBM cloud
• Deploying to Kubernetes on IBM cloud
• Deploying with pm2 and nginx
• Developing and Deploying LoopBack Applications with Appsody

Running and debugging apps

• Setting debug strings
• Using strong-error-handler

Other extensions

• Health check
• Metrics for Prometheus
• Logging
• Running cron jobs
• Pooling

[agnes512]

This might be out of scope but I found Creating Other Forms of APIs page doesn't have ant content, which looks weird to me.

[jannyHou]

Thank you @raymondfeng @agnes512 for the feedback. @agnes512 I think that page is just created as a subsection page, my next PR is going to add all the subsection pages but with some brief contents describing them, they won't be empty.

[dhmlau]

I believe @bajtos had a fix to allow "empty page" not showing up but to expand/collapse the section. "Building REST APIs" item behave this way. Another option to think about. :)

[jannyHou]

@dhmlau thanks for the suggestion! You are right omitting the url is easier, and I removed the empty page. PR created in #6081

[jannyHou]

Related PRs merged, closing