Generate docgen output along with api_docs as part of the build

dart.gyp

 # Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 # for details. All rights reserved. Use of this source code is governed by a
 # BSD-style license that can be found in the LICENSE file.
 
 {
   'targets': [
     {
       'target_name': 'most',
       'type': 'none',
       'dependencies': [
@@ skipping 137 matching lines @@
       'type': 'none',
       'dependencies': [
         'create_sdk',
         'packages',
       ],
     },
     {
       '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.

       ],
     },
     {
       'target_name': 'editor',
       'type': 'none',
       'dependencies': [
         'editor/build/generated/editor_deps.gyp:editor_deps',
 
         # This dependency on create_sdk does not mean that the Editor
         # is rebuilt if the SDK is. It only means that when you build
@@ skipping 42 matching lines @@
     },
     {
       'target_name': 'packages',
       'type': 'none',
       'dependencies': [
         'pkg/pkg.gyp:pkg_packages',
       ],
     },
   ],
 }