Improve JanePHP recipes first-run experience (#2033)

* Improve JanePHP recipes first-run experience

Recipes pointed the generator configs to specification files they never
created, hid all generator output behind a NullOutput (so failures showed
up as raw PHP fatals and successes printed nothing) and always exited 0,
even when generation failed.

- document every config key and the spec file prerequisite in
  config/jane/*.php
- render generator output, format thrown errors and propagate exit codes
  in the recipe bin scripts
- reorder post-install steps: placing the specification file now comes
  before running the generator
- explain when/how to uncomment the generated normalizer service in
  config/packages/jane.yaml

Refs: https://github.com/janephp/janephp/issues/860

* Point recipes to the current documentation website

jane.readthedocs.io is outdated, jane.jolicode.com/latest/ is the
current documentation home.

* Re-trigger QA after adding the license header to the PR description

jane-php/json-schema/6.0/bin/jane-json-schema-generate

@@ -4,12 +4,20 @@
 require __DIR__ . '/../vendor/autoload.php';
 
 use Jane\JsonSchema\Console\Command\GenerateCommand;
-use Symfony\Component\Console\Input\ArrayInput;
-use Symfony\Component\Console\Output\NullOutput;
 use Jane\JsonSchema\Console\Loader\ConfigLoader;
 use Jane\JsonSchema\Console\Loader\SchemaLoader;
+use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Input\ArrayInput;
+use Symfony\Component\Console\Output\ConsoleOutput;
 
 $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader());
 $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/json_schema.php'], $command->getDefinition());
+$output = new ConsoleOutput();
 
-$command->execute($inputArray, new NullOutput());
+try {
+    exit($command->execute($inputArray, $output));
+} catch (\Throwable $throwable) {
+    (new Application())->renderThrowable($throwable, $output->getErrorOutput());
+
+    exit(1);
+}

jane-php/json-schema/6.0/config/jane/json_schema.php

@@ -1,5 +1,20 @@
 <?php
 
+/*
+ * Jane JSON Schema generator configuration.
+ *
+ * - "json-schema-file": path to your JSON Schema specification.
+ *   This file must exist before running bin/jane-json-schema-generate:
+ *   either place your specification at config/jane/json-schema.json,
+ *   or update this path to point to it.
+ * - "root-class": name of the root class generated from your schema.
+ * - "namespace": root namespace of the generated code. It must match the
+ *   PSR-4 mapping you add to your composer.json autoload section.
+ * - "directory": target directory for the generated files.
+ *
+ * See https://jane.jolicode.com/latest/ for all available options.
+ */
+
 return [
     'json-schema-file' => __DIR__ . '/json-schema.json',
     'root-class' => 'MyModel',

jane-php/json-schema/6.0/config/packages/jane.yaml

@@ -3,4 +3,7 @@ services:
         autowire: true
         autoconfigure: true
 
+    # Uncomment the line below once you have generated your code to autowire
+    # the generated normalizers (and the models using them). The namespace
+    # must match the "namespace" key of your config/jane/*.php config file.
 #    MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null

jane-php/json-schema/6.0/post-install.txt

@@ -1,8 +1,8 @@
   * <fg=blue>Finish</> package configuration:
-    1. Configure <comment>config/jane/json_schema.php</> with your specification details
-    2. Run <comment>bin/jane-json-schema-generate</>
+    1. Place your JSON Schema at <comment>config/jane/json-schema.json</>, or update <comment>json-schema-file</> in <comment>config/jane/json_schema.php</>
+    2. Replace <comment>MyApp\Library\Generated</> with your own namespace in <comment>config/jane/json_schema.php</> and in <comment>config/packages/jane.yaml</>
     3. Add <comment>generated/</> directory to your composer autoload definition (eg. <comment>"MyApp\\Library\\Generated\\": "generated/"</>)
-    4. Open <comment>config/packages/jane.yaml</> and replace <comment>MyApp\Library\Generated</> namespace with your generated namespace.
-    5. Then remove line comments
+    4. Run <comment>bin/jane-json-schema-generate</>
+    5. Once generation succeeded, uncomment the service in <comment>config/packages/jane.yaml</> to enable autowiring of the generated normalizer
 
-Documentation: https://jane.readthedocs.io/en/latest/
+Documentation: https://jane.jolicode.com/latest/

jane-php/json-schema/7.0/bin/jane-json-schema-generate

@@ -6,10 +6,18 @@ require __DIR__ . '/../vendor/autoload.php';
 use Jane\Component\JsonSchema\Console\Command\GenerateCommand;
 use Jane\Component\JsonSchema\Console\Loader\ConfigLoader;
 use Jane\Component\JsonSchema\Console\Loader\SchemaLoader;
+use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Input\ArrayInput;
-use Symfony\Component\Console\Output\NullOutput;
+use Symfony\Component\Console\Output\ConsoleOutput;
 
 $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader());
 $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/json_schema.php'], $command->getDefinition());
+$output = new ConsoleOutput();
 
-$command->execute($inputArray, new NullOutput());
+try {
+    exit($command->execute($inputArray, $output));
+} catch (\Throwable $throwable) {
+    (new Application())->renderThrowable($throwable, $output->getErrorOutput());
+
+    exit(1);
+}

jane-php/json-schema/7.0/config/jane/json_schema.php

@@ -1,5 +1,20 @@
 <?php
 
+/*
+ * Jane JSON Schema generator configuration.
+ *
+ * - "json-schema-file": path to your JSON Schema specification.
+ *   This file must exist before running bin/jane-json-schema-generate:
+ *   either place your specification at config/jane/json-schema.json,
+ *   or update this path to point to it.
+ * - "root-class": name of the root class generated from your schema.
+ * - "namespace": root namespace of the generated code. It must match the
+ *   PSR-4 mapping you add to your composer.json autoload section.
+ * - "directory": target directory for the generated files.
+ *
+ * See https://jane.jolicode.com/latest/ for all available options.
+ */
+
 return [
     'json-schema-file' => __DIR__ . '/json-schema.json',
     'root-class' => 'MyModel',

jane-php/json-schema/7.0/config/packages/jane.yaml

@@ -3,4 +3,7 @@ services:
         autowire: true
         autoconfigure: true
 
+    # Uncomment the line below once you have generated your code to autowire
+    # the generated normalizers (and the models using them). The namespace
+    # must match the "namespace" key of your config/jane/*.php config file.
 #    MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null

jane-php/json-schema/7.0/post-install.txt

@@ -1,8 +1,8 @@
   * <fg=blue>Finish</> package configuration:
-    1. Configure <comment>config/jane/json_schema.php</> with your specification details
-    2. Run <comment>bin/jane-json-schema-generate</>
+    1. Place your JSON Schema at <comment>config/jane/json-schema.json</>, or update <comment>json-schema-file</> in <comment>config/jane/json_schema.php</>
+    2. Replace <comment>MyApp\Library\Generated</> with your own namespace in <comment>config/jane/json_schema.php</> and in <comment>config/packages/jane.yaml</>
     3. Add <comment>generated/</> directory to your composer autoload definition (eg. <comment>"MyApp\\Library\\Generated\\": "generated/"</>)
-    4. Open <comment>config/packages/jane.yaml</> and replace <comment>MyApp\Library\Generated</> namespace with your generated namespace.
-    5. Then remove line comments
+    4. Run <comment>bin/jane-json-schema-generate</>
+    5. Once generation succeeded, uncomment the service in <comment>config/packages/jane.yaml</> to enable autowiring of the generated normalizer
 
-Documentation: https://jane.readthedocs.io/en/latest/
+Documentation: https://jane.jolicode.com/latest/

jane-php/open-api-common/6.0/bin/jane-open-api-generate

@@ -4,13 +4,21 @@
 require __DIR__ . '/../vendor/autoload.php';
 
 use Jane\OpenApiCommon\Console\Command\GenerateCommand;
-use Symfony\Component\Console\Input\ArrayInput;
-use Symfony\Component\Console\Output\NullOutput;
 use Jane\OpenApiCommon\Console\Loader\ConfigLoader;
 use Jane\OpenApiCommon\Console\Loader\OpenApiMatcher;
 use Jane\OpenApiCommon\Console\Loader\SchemaLoader;
+use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Input\ArrayInput;
+use Symfony\Component\Console\Output\ConsoleOutput;
 
 $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader(), new OpenApiMatcher());
 $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/open_api.php'], $command->getDefinition());
+$output = new ConsoleOutput();
 
-$command->execute($inputArray, new NullOutput());
+try {
+    exit($command->execute($inputArray, $output));
+} catch (\Throwable $throwable) {
+    (new Application())->renderThrowable($throwable, $output->getErrorOutput());
+
+    exit(1);
+}

jane-php/open-api-common/6.0/config/jane/open_api.php

@@ -1,5 +1,19 @@
 <?php
 
+/*
+ * Jane OpenAPI generator configuration.
+ *
+ * - "openapi-file": path to your OpenAPI specification (JSON or YAML).
+ *   This file must exist before running bin/jane-open-api-generate:
+ *   either place your specification at config/jane/open-api.yaml,
+ *   or update this path to point to it.
+ * - "namespace": root namespace of the generated code. It must match the
+ *   PSR-4 mapping you add to your composer.json autoload section.
+ * - "directory": target directory for the generated files.
+ *
+ * See https://jane.jolicode.com/latest/ for all available options.
+ */
+
 return [
     'openapi-file' => __DIR__ . '/open-api.yaml',
     'namespace' => 'MyApp\Library\Generated',

jane-php/open-api-common/6.0/config/packages/jane.yaml

@@ -3,4 +3,7 @@ services:
         autowire: true
         autoconfigure: true
 
+    # Uncomment the line below once you have generated your code to autowire
+    # the generated normalizers (and the client using them). The namespace
+    # must match the "namespace" key of your config/jane/*.php config file.
 #    MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null

jane-php/open-api-common/6.0/post-install.txt

@@ -1,8 +1,8 @@
   * <fg=blue>Finish</> package configuration:
-    1. Configure <comment>config/jane/open_api.php</> with your specification details
-    2. Run <comment>bin/jane-open-api-generate</>
+    1. Place your API specification at <comment>config/jane/open-api.yaml</>, or update <comment>openapi-file</> in <comment>config/jane/open_api.php</>
+    2. Replace <comment>MyApp\Library\Generated</> with your own namespace in <comment>config/jane/open_api.php</> and in <comment>config/packages/jane.yaml</>
     3. Add <comment>generated/</> directory to your composer autoload definition (eg. <comment>"MyApp\\Library\\Generated\\": "generated/"</>)
-    4. Open <comment>config/packages/jane.yaml</> and replace <comment>MyApp\Library\Generated</> namespace with your generated namespace.
-    5. Then remove line comments
+    4. Run <comment>bin/jane-open-api-generate</>
+    5. Once generation succeeded, uncomment the service in <comment>config/packages/jane.yaml</> to enable autowiring of the generated normalizer
 
-Documentation: https://jane.readthedocs.io/en/latest/
+Documentation: https://jane.jolicode.com/latest/

jane-php/open-api-common/7.0/bin/jane-open-api-generate

@@ -7,10 +7,18 @@ use Jane\Component\OpenApiCommon\Console\Command\GenerateCommand;
 use Jane\Component\OpenApiCommon\Console\Loader\ConfigLoader;
 use Jane\Component\OpenApiCommon\Console\Loader\OpenApiMatcher;
 use Jane\Component\OpenApiCommon\Console\Loader\SchemaLoader;
+use Symfony\Component\Console\Application;
 use Symfony\Component\Console\Input\ArrayInput;
-use Symfony\Component\Console\Output\NullOutput;
+use Symfony\Component\Console\Output\ConsoleOutput;
 
 $command = new GenerateCommand(new ConfigLoader(), new SchemaLoader(), new OpenApiMatcher());
 $inputArray = new ArrayInput(['--config-file' => __DIR__ . '/../config/jane/open_api.php'], $command->getDefinition());
+$output = new ConsoleOutput();
 
-$command->execute($inputArray, new NullOutput());
+try {
+    exit($command->execute($inputArray, $output));
+} catch (\Throwable $throwable) {
+    (new Application())->renderThrowable($throwable, $output->getErrorOutput());
+
+    exit(1);
+}

jane-php/open-api-common/7.0/config/jane/open_api.php

@@ -1,5 +1,19 @@
 <?php
 
+/*
+ * Jane OpenAPI generator configuration.
+ *
+ * - "openapi-file": path to your OpenAPI specification (JSON or YAML).
+ *   This file must exist before running bin/jane-open-api-generate:
+ *   either place your specification at config/jane/open-api.yaml,
+ *   or update this path to point to it.
+ * - "namespace": root namespace of the generated code. It must match the
+ *   PSR-4 mapping you add to your composer.json autoload section.
+ * - "directory": target directory for the generated files.
+ *
+ * See https://jane.jolicode.com/latest/ for all available options.
+ */
+
 return [
     'openapi-file' => __DIR__ . '/open-api.yaml',
     'namespace' => 'MyApp\Library\Generated',

jane-php/open-api-common/7.0/config/packages/jane.yaml

@@ -3,4 +3,7 @@ services:
         autowire: true
         autoconfigure: true
 
+    # Uncomment the line below once you have generated your code to autowire
+    # the generated normalizers (and the client using them). The namespace
+    # must match the "namespace" key of your config/jane/*.php config file.
 #    MyApp\Library\Generated\Normalizer\JaneObjectNormalizer: null

jane-php/open-api-common/7.0/post-install.txt

@@ -1,8 +1,8 @@
   * <fg=blue>Finish</> package configuration:
-    1. Configure <comment>config/jane/open_api.php</> with your specification details
-    2. Run <comment>bin/jane-open-api-generate</>
+    1. Place your API specification at <comment>config/jane/open-api.yaml</>, or update <comment>openapi-file</> in <comment>config/jane/open_api.php</>
+    2. Replace <comment>MyApp\Library\Generated</> with your own namespace in <comment>config/jane/open_api.php</> and in <comment>config/packages/jane.yaml</>
     3. Add <comment>generated/</> directory to your composer autoload definition (eg. <comment>"MyApp\\Library\\Generated\\": "generated/"</>)
-    4. Open <comment>config/packages/jane.yaml</> and replace <comment>MyApp\Library\Generated</> namespace with your generated namespace.
-    5. Then remove line comments
+    4. Run <comment>bin/jane-open-api-generate</>
+    5. Once generation succeeded, uncomment the service in <comment>config/packages/jane.yaml</> to enable autowiring of the generated normalizer
 
-Documentation: https://jane.readthedocs.io/en/latest/
+Documentation: https://jane.jolicode.com/latest/