Reworking documentation

[linusmarco]

The current API reference consists of an inline sample yaml file, which works well for the limited set of options available on the current release, but most of the recent PRs add more options, some of which require more complex explanations.

To deal with this, I think we should move towards something more like this for documenting the options:

bucketName (required)

custom:
  client:
    bucketName: [unique-s3-bucketname]

Use this parameter to specify a unique name for the S3 bucket that your files will be uploaded to.

distributionFolder (optional, defaults to client/dist)

custom:
  client:
    ...
    distributionFolder: [path/to/files]

Use this parameter to specify the path that contains your website files to be uploaded. This path is relative to the path that your serverless.yaml configuration files resides in.

etc.

Thoughts?

[fernando-mc]

@linusmarco Makes sense that the YAML is going to start to be insufficient soon. This looks like a good possibility but I'm not sure how we handle nested attributes here.

I think if possible we should keep one large sample config file somewhere to showcase how it all comes together.

Also, we have additional documentation we might need to do for things like #28 which impact the CLI options.

[linusmarco]

@fernando-mc - good point. I'll think a bit more about this and try to come up with a more complete option that covers nested parameters and CLI options.

Also, I completely agree on keeping a full sample YAML config.

[evanseeds]

How should we handle documenting CloudFormation/AWS features? For example, @linusmarco, in your Pull Request #23, the routing rules you implement mirror CF/S3's routing rules (though with different casing). Is it better to redundantly document all of those ourselves, or point people towards AWS's (often dense and intimidating) documentation?

[linusmarco]

@evanseeds, I think that we should maintain our own documentation for that stuff. As you mentioned, the AWS docs can be pretty opaque, but beyond that, we may not want to exactly mirror their structures for everything, and I wouldn't want to rely on them not adding options or somehow changing their docs. I definitely think it would be good to add links to their docs in our docs as an extra reference where relevant, though.