trailsjs/doc

:books: Trails.js Documentation

Trails Documentation

Available Languages

Language	IETF Language Tag	Maintainer	Link
English	en	Trails Team	doc/en
French	fr	@jaumard @maissani	doc/fr

doc's Issues

Email should not be required

Deployment section

Add a deployment section with :

• General :
  • Think about disabling trailpack-repl for security reason
  • Host must be set to your hostname (or 0.0.0.0) in config/web.js for Express
• on Heroku:
  • Trailpack-repl must be disabled in config/main.js or server will not start

Yo isn't listed added to the Windows Path when installed

Powershell output
yo : The term 'yo' is not recognized as the name of a cmdlet, function, script file, or operable program. Check
spelling of the name, or if a path was included, verify that the path is correct and try again.
At line:1 char:1

• yo trails
• ~~
  • CategoryInfo : ObjectNotFound: (yo:String) [], CommandNotFoundException
  • FullyQualifiedErrorId : CommandNotFoundException

Add documentation on Views

I see that I must configure my view engine in config/views.js. What is that configuration object supposed to look like?

Also where do my html (or ejs or jade) templates go? What is the convention for the file path?

Off line doc

It would be nice to have the possibility to have off line documentation. I use Dash to sync all my documentations off line (https://kapeli.com/docsets) there a lot of doc like npm or express in it. Can be cool to have Trails also.

Chore v1.0 : Implement the How to Deploy Guideline

Feature Deployment Guidlines

Who can contribute?

Any people can contribute on docs.

What's needed

(This issue will be updated each time something is finish or created)
The following list describe what's our needs for the V1.0 of the docs:

• General Configuration
• Heroku Configuration
• Requirements

Publish to NPM

I want to be able to publish these docs to NPM so I can build out the documentation section on trailsjs/trailsjs.io and have it mirror these docs.

Serving Static Files in Express

In Express, one can use app.use and express.static to bind the absolute directory path such as user/home/nodeproject/public to a shortcut: /public, so that html can locate files using a relative path.
For an example expressApp.use('/public', require('express').static(process.cwd() + '/public')); With this I should be able to to display an image using a reative path in my html file, <img src="/public/img/goat.jpg" alt="chilling with a goat">. In the docs, can you show where app.use and express.static should be used ? I tried the init method on the config/web.js file, but it doesn't work.

Extending Subpages don't exist

https://github.com/trailsjs/doc/blob/1a6f1da6819e0c88e999fdbf60f936d7e766db29/en/extend/README.md contains links to files that don't exist.

Also, this is broken: 1cd94de#diff-4e10da212faac65d4e7c2a51398fee32R31

Service example on trailsjs.io and in these docs have incorrect function call

https://trailsjs.io/doc/en/build/service.html#implement-reportcontroller

line: this.services.ReportService.getLatest(cik)
returns: undefined error which stems from this.services
TypeError: Uncaught error: Cannot read property 'ReportService' of undefined

correction: this.app.services

Am I missing some config to avoid this error?

Examples For Sections with Different Web Servers

Situation

• Examples are currently written in Hapi.
• Community members have expressed interest in creating documentation for their preferred trailpacks.

Proposal

• Create an Examples Directory that mimics the doc directory tree per webserver etc
• Link to the example from the official docs.

reference: trailpack-express

config/views

/**
 * Views Configuration
 * (app.config.views)
 *
 * @see http://trailsjs.io/doc/config/views.js
 */
const handlebars = require('handlebars')

module.exports = {
  engine: handlebars
}

Few items:
• Need View docs for context/info about defaults and purpose
• Small typo to be fixed: /views.js to be /views
• Info about potential conflicts between third party views included in onPluginsLoaded in web.js and management therein

Docker deployment documentation

So, I wrote a Docker configuration for Trails.js, including information on scaling with Docker. I would like to migrate this configuration and documentation into Trails.js. Where exactly would this fit in the main Trails.js documentation outline? My best guess right now is under Deploy -> Providers -> Docker.

Below are references to some of the discussions, configuration, and documentation about this subject.

https://gitter.im/trailsjs/trails?at=5996633ba7b406262d9e5a76
https://github.com/jamrizzi/trailblazer/blob/master/Dockerfile
https://github.com/jamrizzi/trailblazer/blob/master/docker-compose.yml
https://github.com/jamrizzi/trailblazer#clustering

Documentation - Add step before running yo trails

Create a new directory before running yo trails. This would prevent the new app from being created in the home folder.

Add documentation on Stores

I am working to get the mongoose trailpack setup and have an error about Error: Migrate must be configured to either "create" or "drop" where I believe I need to configure a Store. It would be nice to have so documentation pointing to a file path in the project where I must configure my Stores. Thank you!

start link on docs is 404

Begin your Journey by clicking Start!
resolves to http://beta.trailsjs.io/en/start when only /start exists.

v3 initial docs

• 0. Start
• 1. Build
  • Controller
  • Service
  • Model
  • Resolver
  • Policy
• 2. Configure
  • main
  • log
  • routes
  • stores
  • i18n
  • web
• 3. Test
  • Unit Testing
  • Integration Testing
• 4. Debug
• 5. Deploy
  • Requirements
  • Providers
  • Sessions
  • Security
  • Scaling
• 6. Extend
  • Trailpack
  • Re-usable Services
  • Server-Side Rendering
    • React.js
    • Angular 2
  • User Management
    • Authentication
    • Permissions
• 7. Upgrade
  • Application
  • Trailpack
• 8. Reference
  • Trails API
  • Trailpack API
  • Controller
  • Service
  • Model
  • Resolver
  • Policy
  • Design Theory
• 9. Support

Chore v1.0 : Implement Concepts

Feature Concepts

Who can contribute?

Any people can contribute on docs.

What's needed

(This issue will be updated each time something is finish or created)
The following list describe what's our needs for the V1.0 of the docs:

• Configuration
• Controllers
• Footprints
• Internationalization
• Models
• Policies ( Locked until get more info about koa #4) by @maissani
• Routing ( currently in progress and discution at #7) by @maissani
• Services
• Sessions
• Trailpacks
• WebServers

Eplainations:

One PR for each features because of unobstrusive contributing and fastest releasing docs.
Double check, you have to Assignee your PR to someone, docs has to be always double or sometimes triple check.

The Currently in progress status

The developper is currently working on it, realeases has to pass the double verification to be merged.

The Locked status

When docs are merged and wait for beeing reopened cause something could be missing.

Disable Travis or update configuration

PR are red because Travis config is wrong, since there only documentation maybe it's better to disable travis...

Extended routing functionality

Currently, route definitions look as follows:

{
    method: [ 'GET' ],
    path: '/api/v1/default/info',
    handler: 'DefaultController.info'
}

Which is a it cumbersome, especially if you need to define lots of routes. Would be nice to be able to have a more succinct syntax, perhaps something like so?

Router
   .post( '/user', UserCtl.create)
   .put( '/user',   auth.isAuthenticated(), UserCtl.update)

Just an example, but you get my point I hope.

Also nested routes would be really nice, mostly for convenience, so stuff like this can be done:

{
    method: [ 'GET' ],                         // this here would/could be optional
    path: '/api/v1/default',
    handler: 'DefaultController.info'  // so would this guy

    subRoutes: [{
         method: [ 'GET' ],
         path: '/info',   // this then becomes /api/v1/default
         handler: 'DefaultController.info'
     }]
}

Also just an example, but I hope the general idea comes through.
That should be all, I'll add updates if anything else comes to mind
:)

News?

We're in 2.0 but we still don't have a complete documentation for improving the onboarding experience for the users and solving common issues

You plan to release somethings is the next months?
In case, there's anything I can help with?

Git error appears after the generator is complete

┌───────────────────────────────────────────┐
│ Your Trails Application has been created! │
│ --- │
│ To start your application, run: npm start │
└───────────────────────────────────────────┘

'git' is not recognized as an internal or external command,
operable program or batch file.
'git' is not recognized as an internal or external command,
operable program or batch file.

add documentation search field using Github search API

e.g. https://github.com/trailsjs/doc/search?utf8=%E2%9C%93&q=resolvers&type=Code