Added description to landing page examples (#1185)

* Added description to landing page examples

* Added missing headlines to example page

Author: norberttech

examples/topics/data_source/array/description.md

@@ -0,0 +1 @@
+Read data directly from a php associative array.  Relays on `array_to_rows` DSL function.

examples/topics/data_source/csv/description.md

@@ -0,0 +1,22 @@
+Read data from a csv file.
+
+```php
+function from_csv(
+    string|Path|array $path,
+    bool $with_header = true,
+    bool $empty_to_null = true,
+    ?string $delimiter = null,
+    ?string $enclosure = null,
+    ?string $escape = null,
+    int $characters_read_in_line = 1000,
+    ?Schema $schema = null
+):
+``` 
+
+* `with_header` - default true, if false, the first row will be treated as data
+* `empty_to_null` - default false, if true, empty string will be treated as null
+* `delimiter` - the delimiter of the csv file, when not set, it will be auto detected
+* `enclosure` - the enclosure of the csv file, when not set, it will be auto detected
+* `escape` - default `\`, the escape character of the csv file
+* `characters_in_line` - default `1000`, size of chunk used to read lines from the file
+* `schema` - the schema of the csv file, when not set, it will be auto detected

examples/topics/data_source/json/description.md

@@ -0,0 +1,12 @@
+Read data from a json file.
+
+```php
+function from_json(
+    string|Path|array $path,
+    ?string $pointer = null,
+    ?Schema $schema = null,
+);
+```
+
+* `pointer` - default null, used to iterate only results of a subtree, read more about [pointers](https://github.com/halaxa/json-machine#parsing-a-subtree)
+* `schema` - the schema of the csv file, when not set, it will be auto detected

examples/topics/data_source/parquet/description.md

@@ -0,0 +1,16 @@
+Read data from a json file.
+
+```php
+function from_parquet(
+    string|Path|array $uri,
+    array $columns = [],
+    Options $options = new Options(),
+    ByteOrder $byte_order = ByteOrder::LITTLE_ENDIAN,
+    ?int $offset = null,
+);
+```
+
+* `columns` - default [], list of columns to read, when empty, all columns will be read
+* `options` - custom Parquet Reader [Options](https://github.com/flow-php/flow/blob/1.x/src/lib/parquet/src/Flow/Parquet/Options.php)
+* `byte_order` - default `ByteOrder::LITTLE_ENDIAN`, the byte order of the parquet file
+* `offset` - default null, rows to skip from the beginning of the file 

examples/topics/data_source/xml/description.md

@@ -0,0 +1,10 @@
+Read data from a json file.
+
+```php
+function from_xml(
+    string|Path|array $path,
+    string $xml_node_path = ''
+);
+```
+
+* `xml_node_path` - default '', the path to the node to read, when empty, the root node will be read. It's not xpath, it is just a sequence of node names separated with slash.

examples/topics/schema/inferring/description.md

@@ -0,0 +1,2 @@
+Schema inferring is a process of generating a schema from a whole or part of the dataset.   
+Once schema is inferred, it can be saved and used to speed up next dataset processing.

src/adapter/etl-adapter-parquet/src/Flow/ETL/Adapter/Parquet/functions.php

@@ -13,26 +13,26 @@
 use Flow\Parquet\{ByteOrder, Options};
 
 /**
- * @param array<Path>|Path|string $uri
+ * @param array<Path>|Path|string $path
  * @param array<string> $columns
  *
  * @return Extractor
  */
 function from_parquet(
-    string|Path|array $uri,
+    string|Path|array $path,
     array $columns = [],
     Options $options = new Options(),
     ByteOrder $byte_order = ByteOrder::LITTLE_ENDIAN,
     ?int $offset = null,
 ) : Extractor {
-    if (\is_array($uri)) {
+    if (\is_array($path)) {
         $extractors = [];
 
         if ($offset !== null) {
             throw new InvalidArgumentException('Offset can be used only with single file path, not with pattern');
         }
 
-        foreach ($uri as $filePath) {
+        foreach ($path as $filePath) {
             $extractors[] = new ParquetExtractor(
                 $filePath,
                 $options,
@@ -45,7 +45,7 @@ function from_parquet(
     }
 
     return new ParquetExtractor(
-        \is_string($uri) ? Path::realpath($uri) : $uri,
+        \is_string($path) ? Path::realpath($path) : $path,
         $options,
         $byte_order,
         $columns,

web/landing/assets/controllers/all_links_external_controller.js

@@ -0,0 +1,13 @@
+import {Controller} from '@hotwired/stimulus';
+
+/* stimulusFetch: 'lazy' */
+export default class extends Controller
+{
+    connect()
+    {
+        this.element.querySelectorAll('a').forEach(link => {
+                link.target = '_blank';
+                link.rel = 'noopener';
+        });
+    }
+}

web/landing/assets/styles/app.css

@@ -59,4 +59,28 @@ code {
 
 #blog-post hr {
     @apply text-blue-100 my-4 border-t-2 rounded;
+}
+
+#example-description h1 {
+    @apply font-bold text-2xl;
+}
+
+#example-description h2 {
+    @apply font-bold text-xl mt-4;
+}
+
+#example-description h1, h2, ul, hr, p {
+    @apply mb-3;
+}
+
+#example-description ul {
+    @apply list-disc pl-6;
+}
+
+#example-description hr {
+    @apply text-blue-100 my-4 border-t-2 rounded;
+}
+
+#example-description code {
+    @apply text-orange-100;
 }

web/landing/composer.json

@@ -23,7 +23,7 @@
         "monolog/monolog": "^3.5",
         "symfony/monolog-bundle": "^3.10",
         "coduo/php-humanizer": "^4.0",
-        "twig/markdown-extra": "^3.8",
+        "twig/markdown-extra": "^3.11",
         "twig/extra-bundle": "^3.8",
         "league/commonmark": "^2.4"
     },

web/landing/composer.lock

@@ -4,12 +4,12 @@
 
 namespace Flow\Website\Controller;
 
-use Flow\Website\Service\{Examples};
+use Flow\Website\Service\Examples;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\Routing\Attribute\Route;
 
-final class DefaultController extends AbstractController
+final class ExamplesController extends AbstractController
 {
     public function __construct(
         private readonly Examples $examples,
@@ -30,19 +30,12 @@ public function example(string $topic, string $example) : Response
             'examples' => $examples,
             'currentTopic' => $topic,
             'currentExample' => $example,
+            'description' => $this->examples->description($currentTopic, $currentExample),
             'code' => $this->examples->code($currentTopic, $currentExample),
             'output' => $this->examples->output($currentTopic, $currentExample),
         ]);
     }
 
-    #[Route('/', name: 'main')]
-    public function main() : Response
-    {
-        return $this->render('main/index.html.twig', [
-            'topics' => $this->examples->topics(),
-        ]);
-    }
-
     #[Route('/{topic}/', name: 'topic', priority: 10)]
     public function topic(string $topic) : Response
     {
@@ -57,6 +50,7 @@ public function topic(string $topic) : Response
             'examples' => $examples,
             'currentTopic' => $currentTopic,
             'currentExample' => $currentExample,
+            'description' => $this->examples->description($currentTopic, $currentExample),
             'code' => $this->examples->code($currentTopic, $currentExample),
             'output' => $this->examples->output($currentTopic, $currentExample),
         ]);

web/landing/src/Flow/Website/Controller/DefaultController.php renamed to web/landing/src/Flow/Website/Controller/ExamplesController.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Website\Controller;
+
+use Flow\Website\Service\{Examples};
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+final class HomeController extends AbstractController
+{
+    public function __construct(
+        private readonly Examples $examples,
+    ) {
+    }
+
+    #[Route('/', name: 'home')]
+    public function home() : Response
+    {
+        return $this->render('main/index.html.twig', [
+            'topics' => $this->examples->topics(),
+        ]);
+    }
+}

web/landing/src/Flow/Website/Controller/HomeController.php

@@ -21,6 +21,17 @@ public function code(string $topic, string $example) : string
         return \file_get_contents($path);
     }
 
+    public function description(string $topic, string $example) : ?string
+    {
+        $path = \sprintf('%s/topics/%s/%s/description.md', \realpath($this->examplesPath), $topic, $example);
+
+        if (false === \file_exists($path)) {
+            return null;
+        }
+
+        return \file_get_contents($path);
+    }
+
     /**
      * @return string[]
      */

web/landing/src/Flow/Website/Service/Examples.php

@@ -51,7 +51,7 @@
 <body class="scroll-smooth bg-black text-white">
     <header class="py-2 text-white bg-blue-200">
         <div class="mx-auto max-w-screen-xl px-4 flex items-center justify-between">
-            <a href="{{ path('main') }}">
+            <a href="{{ path('home') }}">
                 <img src="{{ asset('images/logo.svg') }}" alt="flow php" width="176" height="48">
             </a>
 

web/landing/templates/base.html.twig

@@ -10,6 +10,7 @@
 
 {% block main %}
     <div class="py-10 px-2 sm:px-4 mx-auto max-w-screen-xl" data-hx-boost="true">
+        <h2 class="mb-4 text-2xl font-semibold tracking-wide">Examples:</h2>
         <nav class="font-medium text-center bg-orange-100 rounded">
             <ul class="flex whitespace-nowrap overflow-auto justify-between">
                 {% for topic in topics %}
@@ -37,7 +38,18 @@
             </nav>
 
             <div id="example" class="-mt-36 pt-36">
+                {% if description %}
+                    <h2 class="text-xl mt-5 mb-5">Description</h2>
+                    <article id="example-description"
+                             class="rounded px-4 pt-4 overflow-auto shadow-2xl shadow-gray rounded border-gray border-2 relative mb-10"
+                            {{ stimulus_controller('all_links_external') }}
+                    >
+                        {{ description|markdown_to_html }}
+                    </article>
+                {% endif %}
+
                 {% apply spaceless %}
+                    <h2 class="text-xl mt-5 mb-5">Code</h2>
                     <pre class="rounded p-4 overflow-auto shadow-2xl shadow-gray rounded border-gray border-2 relative">
                         <button class="absolute top-0 right-0 bg-orange-100 rounded px-4 leading-9 [&.copied]:before:content-['Copied!'] before:absolute before:-translate-x-24" title="copy code" data-clipboard-target="#code" {{ stimulus_controller('clipboard') }}>
                             <img src="{{ asset('images/icons/copy.svg') }}" alt="copy code" width="20" height="20" class="inline">