Generate docgen output along with api_docs as part of the build

dart.gyp

Index: dart.gyp
diff --git a/dart.gyp b/dart.gyp
index 228580c9c2c73c2bf532451231b0d649b8d7dc16..9db97a92c9f2a16984a41fb4ce40742df4df4291 100644
--- a/dart.gyp
+++ b/dart.gyp
@@ -155,7 +155,10 @@
       'target_name': 'api_docs',
       'type': 'none',
       'dependencies': [
+        # TODO(alanknight) : Once we're fully switched over to the new
+        # viewer remove the old api_docs gyp file.
         'utils/apidoc/apidoc.gyp:api_docs',
+        'utils/apidoc/docgen.gyp:docgen',

[kustermann, 2013/11/18 09:57:08]

I think this could cause issues. These two dependencies are executed in a random
order (if I'm not missing something).

apidocs is called with:
'--out=<(PRODUCT_DIR)/api_docs',

docgen is called with:
 '--out=<(PRODUCT_DIR)/api_docs/docgen'

Both of these tools will, as a first step, clean the output directory.

Here's what can happen:
 1. docgen is executed
    - will clean "<(PRODUCT_DIR)/api_docs/docgen"
    - will generate documentation into "<(PRODUCT_DIR)/api_docs/docgen"
 2. apidocs is executed
    - will clean "<(PRODUCT_DIR)/api_docs"
    - will generate documentation into "<(PRODUCT_DIR)/api_docs"

In this situation the new documentation was deleted in the 2nd step.

If reasoning is correct, you have the following options
 - have only one gyp target which create the api documentation
    => You could for example write a python script which executes first the old
apidocs tool and then the new docgen tool

 - you could make the new docgen action depend on the output of the old apidocs
(i.e. the input files of the 

 - you could output the new documentation into a different directory than the
old one.

[Alan Knight, 2013/11/18 20:34:50]

Made docgen depend on the apidocs target. It seems like that should be
sufficient, but my understanding of gyp is limited. Using the same directory
seemed good because it avoids needing to modify the uploading code, and this is
semantically the same stuff, with the idea that at some point we stop generating
apidocs output.

[ahe, 2013/11/18 20:56:44]

Unfortunately, this is one of the biggest gotchas with GYP: depending on a
target has no impact on actions.

For actions to be executed in order, one action must declare an output file, and
the other must list that output file as an input. So you need to change the
docgen action so it lists an output of apidocs as input.

       ],
     },
     {