JSDoc integration?

[Holger-Will]

should we integrate with JSDoc?

[alexlemaire]

We can give it a shot yep

[alexlemaire]

There is now a new action action-generate-docs that can be used in a workflow to automatically generate documentation for a repository.

As for now it supports action and package type of repository. The documentation is built using the following logic:

• action uses action.yml metadata file from the action
• package uses JSDoc style comments in all .js files found in the repository (excluding patterns from .gitignore)
• layer uses main serverless.yml configuration file to extract layers meta data (and all installed NPM packages for each of them) and output documentation accordingly. Supports multi layer and Serverless variables resolution
• lambda uses main serverless.yml configuration file to extract lambda functions meta data and output documentation accordingly. Supports multi lambda and Serverless variables resolution. It also supports layers: it'll document layers attached to each lambdas and also output layer documentation if those layers are directly part of the stack
• api uses the same logic as layer and lambda to document any layers and lambdas defined in the API. It also individually documents every endpoints.
• element uses the same logic as package. It limits the documentation generation to the main file (extracted from main field in package.json) and will also print out usage instructions (via kaskadi.s3-push.files in package.json)

Notes:

• for any type of repository we can pass a template (.md file containing a {{>main}} token) which will be used as base for the documentation and in which {{>main}} will be replace by the actual output from the documentation generator
• all documentation is written in README.md

Automatic documentation generation implemented in repositories. CI/CD pipeline integration as follow:

• action/layer/lambda/api/element: a separate generate-docs workflow generates the documentation automatically and pushes it
• package: a generate-docs job inside of publish workflow generates and pushes the documentation. publish job inside of publish workflow waits on generate-docs to finish and then pulls any new documentation before publishing the package

All documentations are pushed by our kaskadi-bot (GPG signed) but that can be modified.

Examples below:

• action: action-init
• package: mws-client
• layer: template-kaskadi-layer
• lambda: set-amz-stocks
• api: products-api
• element: template-kaskadi-element (soon)

Closing for now!

EDIT 21.09.2020: layer now supported! EDIT 22.09.2020: lambda now supported! EDIT 29.09.2020: api now supported! Also did some tweaks and improvements to layer and lambda EDIT 20.10.2020: element now supported! Improved api, lambda and layer modules in the meantime as well as refactored package to reuse logic into element