OpenWhisk should have a well organized doc website.

Current status

OpenWhisk website has a menu item "Documentation" in menu "Docs", which is a hyperlink to docs folder in apache/incubator-openwhisk Github repo.

The docs folder in apache/incubator-openwhisk Github repo is a mix of all kinds of MD files, including:

  • README.md: entry point
  • about.md: System overview
  • actions.md: creating and invoking actions
  • annotation.md: annotations used in CLI for OpenWhisk assets ( i.e. actions, triggers, rules, web actions, feeds, etc )
  • apigateway.md: How to use API Gateway
  • catalog.md: How to use OpenWhisk enabled external services in the /whisk.system namespace.
  • cli.md: how to set up, config and use CLI
  • feeds.md: Implementing feeds
  • mobile_sdk.md: how to install and use the mobile SDK
  • packages.md: how to create and use packages with CLI
  • reference.md: OpenWhisk system details
  • rest_api.md: how to use REST APIs to manage OpenWhisk assets
  • samples.md: OpenWhisk samples
  • triggers_rules.md: what is triggers & rules and how to use triggers & rules.
  • use_cases.md: common use cases of OpenWhisk
  • webactions.md: what is web action and how to create and use web actions
  • images: useful images in docs and whisk icons in different size
  • dev/feature.md: Web actions potential future enhancements

There are also README.md documents in every folder and repository. We should integrate them all together and give a whole picture.

Proposal

Goals
  1. Well organize the existing docs and publish in OpenWhisk website as an integrated documentation.
  2. Add scala docs as a developer reference, also a part of the integrated documentation.
Outlines and contents
  1. Quick start
  2. Deployment Guides
    1. Set up with Mac (incubator-openwhisk/tools/macos/README.md)
    2. Set up with Ubuntu (incubator-openwhisk/tools/ubuntu-setup/README.md)
    3. Setting up OpenWhisk with Docker-machine (incubator-openwhisk/tools/macos/docker-machine/README.md)
    4. Deploying OpenWhisk using Ansible (incubator-openwhisk/ansible/README.md)
    5. Deploying distributed OpenWhisk using Ansible (incubator-openwhisk/ansible/README_DISTRIBUTED.md)
  3. Programming Guides
    1. Event driven programming model
    2. Actions (actions.md)
    3. Triggers (triggers_rules.md)
    4. Rules (triggers_rules.md)
    5. Feeds (feeds.md)
    6. Web actions (webactions.md)
    7. API Gateway (apigateway.md)
    8. Packages (packages.md)
  4. CLI Guides (cli.md)
  5. System Catalog Guides (catalog.md)
  6. Packages Guides
    1. incubator-openwhisk-package-alarms
    2. incubator-openwhisk-package-cloudant
    3. incubator-openwhisk-package-jira
    4. incubator-openwhisk-package-kafka
    5. incubator-openwhisk-package-pushnotifications
    6. incubator-openwhisk-package-rss
  7. API Client Guides
    1. incubator-openwhisk-client-go
    2. incubator-openwhisk-client-js
    3. incubator-openwhisk-client-python
    4. incubator-openwhisk-client-swift
  8. Useful Tools
    1. Whisk Deploy
    2. Dev tools
  9. Restful APIs
    1. rest_api.md
  10. OpenWhisk Contributor Guides
    1. contributor guides
    2. Reference: Scala docs
Back end technologies

TBD

  • No labels