Documentation Revamp

[sanathkr]

Parent tracking issue to discuss improvements to SAM documentation. Here are some of the things planned:

• Internals of the resources generated by SAM
• Debugging/Troubleshooting guide: FAQ style section addressing following:
  • Adding event triggers on external resources,
  • Using Policy & Role together in Function
  • Intrinsic function compatibility
  • CFN compatibility
  • How to use DeploymentPreference Hook functions
  • Work arounds for unsupported features: APIGW features like CORS etc, DDB features. Link to examples on how to work around for these features.
  • How to add ApiKeys to AWS::Serverless::Api
  • CloudFormation deployments:
    • Nested stacks
    • Large templates
    • Inlining Swagger templates
  • AWS CLI issues:
    • aws cloudformation package/deploy commands
• SAM/CloudFormation compatibility - Supported Intrinsic functions, resources, DependsOn, generated logicalIds, etc
• Write up a process doc on how we will maintain the documentation - Basically when an issue is closed (except for Duplicates), one of the action item is to add/update the doc

Feel free to comment here if you think something is missing from this list. We will add them.

How to Contribute

If you find a mistake or a missing doc and want to contribute, feel free send a pull requests against the docs branch. Doc changes are being made on the docs branch and made available on SAM Docs Website automatically through a TravisCI build.

Download & Edit docs

1. git clone https://github.com/awslabs/serverless-application-model.git
2. cd serverless-application-model
3. git checkout docs
4. Make your documentation changes to .rst files under docs folder. These are reStructuredText files, similar to Markdown, but way more powerful. Checkout cheatsheet here - https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst. All popular IDEs have a plugin that can render rst files. I use VSCode with this plugin that is very good
5. Push the changes up to your local fork and send us a pull request

Build the docs website locally

We use Sphinx to generate the website from docs. Sphinx compiles rst files and shows errors if any. This is recommended before pushing to Github to make sure your rst files are valid. Here are the instructions to build it yourself:

1. Make sure you have virtualenv installed
2. cd docs/website
3. virtualenv venv
4. source venv/bin/activate
5. pip install -r requirements.txt
6. make clean && make html

This will create HTML pages on the docs/website_build/ directory. Open the docs/website/_build/index.html file and start browsing.

[sanathkr]

For those of you following along the Issue, we just pushed a first set of changes to docs branch. Internals of resources generated by SAM is done.

And there is a pretty website as well - https://awslabs.github.io/serverless-application-model/. Still very much a work in progress

[yunchancho]

I ask you that specific information of SAM should be informed on SAM documentations.

As you know, each property of AWS resources has one of three update behaviors like the followings
(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html)

 'Interruption', 'No interruption', 'Replacement'

Unfortunately, I couldn't find any information about update behavior of the following SAM resources.

AWS::Serveless::Function
AWS::Serverless::Api
AWS::Serverless::SimpleTable

I need such information in order to prepare specific solution for interruptions on updating SAM resources. And other developers using SAM would need it for safe deployment.

If you have any information about what each property of SAM resources has as update behavior, please share it here first.

[jfuss]

@yunchancho Love the suggestion! This is a great thing we should add to our documentation. To keep this issue scope to the initial intent, could you please create a new Feature Request Issue and add the details you asked for here? If you have any suggestions on where this documentation could be added to our docs, would you mind adding those details as well?

[jfuss]

@yunchancho My appologizes! You did raise an issue (#292). I will reply there.

[bedge]

This is a problem for large corporate deployments where one needs to account for many different cases within the template. Almost a non-starter as it immediately forces one into non-optimal fallback mode in step 1.

eg: VPC/SubnetId
These are of value at deployment time only.
Setting these in the env mixes them up with variable that are intentionally modifiable.

Edit:
It's worse than inconvenient, as if VpcConfig exists, it must be set. This is really a case that required conditionals.

[david-katz]

Note that the comments made in various tickets about the intrinsic names for Stage (and documented here: https://awslabs.github.io/serverless-application-model/internals/generated_resources.html#aws-serverless-api) appear now to be wrong.

The "logicalId" for a Stage created by SAM now appears simply to be <API logical id>Stage (where logical id is just the name you gave the Serverless::API in your template.)

When I added in the stage name, I got an error that no such element exists and the stack deployment failed. A comment in #259 helped solve the issue for me.

If these names did indeed change, this seems to be in contradiction to statements made by the SAM team that we can count on these intrinsic names and they will never change. Or have I misunderstood something here?

[jlhood]

@david-katz Apologies, that link is no longer valid. This documentation page should be considered the source of truth for logicalIds generated by SAM:

https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api

I've edited the comment in #259 to remove that link so it doesn't cause further confusion.

[awsjeffg]

We've recently done a major docs refresh. If you feel there is something missing from the current docs, please open a new issue.