Reorganize actions doc. #3816

rabbah · 2018-06-27T17:55:06Z

This PR introduces a language-agnostic (mostly) basic introduction to working with actions. And it splits the language/runtime specific tutorials and references into their own markdowns. This is based on discussion with @csantanapr and @akrabat. All feedback appreciated and welcomed.

Description

Related issue and scope

I opened an issue to propose and discuss this change (#????)

My changes affect the following components

Types of changes

Bug fix (generally a non-breaking change which closes an issue).
Enhancement or new feature (adds new functionality).
Breaking change (a bug fix or enhancement which changes existing behavior).

Checklist:

I signed an Apache CLA.
I reviewed the style guides and followed the recommendations (Travis CI will check :).
I added tests to cover my changes.
My changes require further changes to the documentation.
I updated the documentation where necessary.

codecov-io · 2018-06-27T23:13:48Z

Codecov Report

Merging #3816 into master will decrease coverage by 0.03%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3816      +/-   ##
==========================================
- Coverage   75.19%   75.16%   -0.04%     
==========================================
  Files         136      136              
  Lines        6383     6386       +3     
  Branches      387      389       +2     
==========================================
  Hits         4800     4800              
- Misses       1583     1586       +3

Impacted Files	Coverage Δ
...ols/admin/src/main/scala/whisk/core/cli/Main.scala	`25.33% <0%> (-1.06%)`	⬇️
...c/main/scala/whisk/core/database/UserCommand.scala	`97.77% <0%> (ø)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c202ba7...ba211ab. Read the comment docs.

akrabat · 2018-06-28T08:35:15Z

docs/actions.md

-
-In addition, we recommend that you review the following topics:
+The rest of this document provides a [basic tutorial](#the-basics) for invoking an action, passing parameters to it, and
+inspecting the result. We recommend that you get familiar with the following topics first.


We can't recommend that you get familiar with the following topics first (i.e. before the basic tutorial) when the first prerequisite topic item is the basic tutorial.

akrabat · 2018-06-28T08:37:52Z

docs/actions.md

+For more information regarding action invocations using the REST interface, see [Using REST APIs with OpenWhisk](rest_api.md#actions).
+
+Another way of invoking an action which does not require authentication is via
+[web actions](https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md#web-actions).


Can we use a relative link here?

bdelacretaz · 2018-06-28T08:38:45Z

I like it! I think it makes perfect sense to explain the general principles of Actions and farm out the language-specific details. It might be useful to mention what happens under the hood when running actions (i.e. /init and /run calls to a container) but maybe that's too much detail at this level.

akrabat · 2018-06-28T08:42:05Z

docs/php-actions.md

+
+The PHP runtime will automatically include Composer's autoloader for you, so you can immediately use the dependencies in your action code.
+
+Note that if you don't include your own `vendor` folder, then the runtime will include one for you. The packages included are listed in the [reference](https://github.com/apache/incubator-openwhisk/blob/master/docs/reference.md#composer-packages).


Link is wrong - the composer-packages section is further down the page.

akrabat · 2018-06-28T08:48:24Z

docs/swift-actions.md

+```
+
+
+See the Swift [reference](./reference.md#swift-actions) for more information about the Swift runtime.


Link is wrong - reference is further down the page now.

akrabat · 2018-06-28T08:50:39Z

docs/node-actions.md

+  ```
+  ok: created action hello
+  ```
+  The CLI automatically infers the type of the action by using the source file extension. For `.js` source files, the action runs by using a Node.js 6 runtime. You can also create an action that runs with Node.js 8 by explicitly specifying the parameter `--kind nodejs:8`. For more information, see the Node.js 6 vs 8 [reference](./reference.md#javascript-runtime-environments).


Link is wrong - reference is further down the page.

akrabat · 2018-06-28T08:51:22Z

docs/node-actions.md

+  }
+  ```
+
+  Note that the action in the example uses the JavaScript `request` library to make an HTTP request to the Yahoo Weather API, and extracts fields from the JSON result. The [References](./reference.md#javascript-runtime-environments) detail the Node.js packages that you can use in your actions.


Link to reference needs updating.

akrabat · 2018-06-28T08:54:57Z

docs/docker-actions.md

+  wsk action update example --docker janesmith/blackboxdemo
+  ```
+
+  You can find more information about creating Docker actions in the [References](./reference.md#docker-actions) section.


The "Docker actions" section is no longer in reference.md, but I can't find it in docker-actions.md either!

akrabat · 2018-06-28T08:55:34Z

docs/php-actions.md

+wsk action create helloPHP hello.php
+```
+
+The CLI automatically infers the type of the action from the source file extension. For `.php` source files, the action runs using a PHP 7.1 runtime. See the PHP [reference](./reference.md#php-actions) for more information.


Link needs updating

csantanapr · 2018-06-28T11:14:24Z

This is great I wanted this split for the longest time +1

What do you think is all files start with “actions-*”? Like “actions-java.md”

I think is my OCD and I will have trouble find the files. What used to be in actions.md now is in actions-java.md also when listing the files all languages are together so it’s easy to see the ones available.

dgrove-oss · 2018-06-28T12:22:58Z

This is great. fwiw, it looks like I have the same OCD as Carlos; I'd also put an action prefix on all the files so that an 'ls' grouped them nicely.

rabbah · 2018-06-28T12:30:11Z

hehe ok. I named them as I did for tab completion but I will rename.

rabbah · 2018-06-28T18:25:50Z

Renamed the files. @akrabat thanks for flagging the broken links - I'll fix these in the next pass. I tried to address the flow in the parent doc per your comment.

rabbah · 2018-06-28T18:34:37Z

@bdelacretaz I added a commit to introduce init and run, cold vs warm start.

rabbah · 2018-06-29T01:47:32Z

@akrabat I've fixed the links and made a pass to update all the docs for the runtimes as well while at it.

akrabat · 2018-06-29T08:17:14Z

docs/actions-php.md

+use the dependencies in your action code.
+
+Note that if you don't include your own `vendor` folder, then the runtime will include one for you.
+The following PHP extensions are available in addition to the standard ones:


Need to separate PHP extensions list from the Composer info as they aren't the same thing. Composer manages PHP components, PHP extensions are compiled C libraries that are loaded by the language and the the user cannot add to or remove them.

thanks @akrabat for the review - I think addressed in my last commit if you can kindly look again.

Yes. That's great. Thanks.

csantanapr · 2018-06-29T19:52:42Z

❤️ the move of references to each runtime language

csantanapr

LGTM 🎉

* Refactor actions markdown so each lang/runtime is its own doc file.

rabbah added documentation review Review for this PR has been requested and yet needs to be done. labels Jun 27, 2018

Refactor actions markdown so each lang/runtime is its own doc file.

7b51dc6

rabbah force-pushed the docs branch 2 times, most recently from 94c623b to 2f81837 Compare June 27, 2018 22:55

Add missing anchor, fix some typos.

54b852b

rabbah force-pushed the docs branch from 2f81837 to 54b852b Compare June 27, 2018 22:59

Some more updates.

3249e58

akrabat reviewed Jun 28, 2018

View reviewed changes

Rename runtime files, small tweaks to intro paras.

a0b1546

Add some details about init vs run.

f74feae

Update the language-specific docs.

bbb828c

akrabat reviewed Jun 29, 2018

View reviewed changes

Update PHP doc.

ba211ab

rabbah assigned csantanapr Jun 29, 2018

csantanapr approved these changes Jun 29, 2018

View reviewed changes

csantanapr merged commit bad0260 into apache:master Jun 29, 2018

BillZong pushed a commit to BillZong/openwhisk that referenced this pull request Nov 18, 2019

Reorganize actions docs (apache#3816)

5264074

* Refactor actions markdown so each lang/runtime is its own doc file.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reorganize actions doc. #3816

Reorganize actions doc. #3816

rabbah commented Jun 27, 2018

codecov-io commented Jun 27, 2018 •

edited

akrabat Jun 28, 2018

akrabat Jun 28, 2018

bdelacretaz commented Jun 28, 2018

akrabat Jun 28, 2018 •

edited

akrabat Jun 28, 2018

akrabat Jun 28, 2018

akrabat Jun 28, 2018

akrabat Jun 28, 2018

akrabat Jun 28, 2018

csantanapr commented Jun 28, 2018

dgrove-oss commented Jun 28, 2018

rabbah commented Jun 28, 2018

rabbah commented Jun 28, 2018

rabbah commented Jun 28, 2018

rabbah commented Jun 29, 2018 •

edited

akrabat Jun 29, 2018

rabbah Jun 29, 2018

akrabat Jun 29, 2018

csantanapr commented Jun 29, 2018

csantanapr left a comment


		The PHP runtime will automatically include Composer's autoloader for you, so you can immediately use the dependencies in your action code.

		Note that if you don't include your own `vendor` folder, then the runtime will include one for you. The packages included are listed in the [reference](https://github.com/apache/incubator-openwhisk/blob/master/docs/reference.md#composer-packages).

		```


		See the Swift [reference](./reference.md#swift-actions) for more information about the Swift runtime.

Reorganize actions doc. #3816

Reorganize actions doc. #3816

Conversation

rabbah commented Jun 27, 2018

Description

Related issue and scope

My changes affect the following components

Types of changes

Checklist:

codecov-io commented Jun 27, 2018 • edited

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bdelacretaz commented Jun 28, 2018

akrabat Jun 28, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csantanapr commented Jun 28, 2018

dgrove-oss commented Jun 28, 2018

rabbah commented Jun 28, 2018

rabbah commented Jun 28, 2018

rabbah commented Jun 28, 2018

rabbah commented Jun 29, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

csantanapr commented Jun 29, 2018

csantanapr left a comment

Choose a reason for hiding this comment

codecov-io commented Jun 27, 2018 •

edited

akrabat Jun 28, 2018 •

edited

rabbah commented Jun 29, 2018 •

edited