minor docs improvements

Author: fibo

.github/CONTRIBUTING.md

@@ -30,7 +30,7 @@ node --env-file .typescript.env ./examples/doc-snippets/helloWorld.ts
 
 ## Build
 
-Once done with [Requirements](#requirements) to build the project, just run:
+To build everything, once done with [Requirements](#requirements) just run:
 
 ```sh
 npm run build

dflow.ts

@@ -27,7 +27,7 @@ export type DflowDataType =
   | "array"
   | "object";
 
-// Inputs, outputs and links.
+// Inputs, outputs, links and nodes.
 // ////////////////////////////////////////////////////////////////////
 
 /** Connects two nodes in the graph. */
@@ -78,9 +78,6 @@ export type DflowOutput = {
   types: DflowDataType[];
 };
 
-// DflowNode
-// ////////////////////////////////////////////////////////////////////
-
 /** Defines a block of code: it can have inputs and outputs. */
 export type DflowNode = {
   kind: string;
@@ -434,9 +431,7 @@ export class Dflow {
     }
   }
 
-  /**
-   * A graph contains nodes and links.
-   */
+  /** A graph contains nodes and links. */
   get graph(): DflowGraph {
     const node: DflowGraph["node"] = {};
     const data: DflowGraph["data"] = {};
@@ -506,6 +501,8 @@ export class Dflow {
    * ```ts
    * Dflow.input([], { name: "foo" })
    * ```
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.input} for more examples.
    */
   static input(
     typing: DflowDataType | DflowDataType[] = [],
@@ -523,8 +520,10 @@ export class Dflow {
    * @example Named output with `number` type.
    *
    * ```ts
-   * Dflow.output("number", { name: "amount" })
+   * Dflow.output("number", { name: "count" })
    * ```
+   *
+   * @see {@link https://fibo.github.io/dflow/#dflow.output} for more examples.
    */
   static output(
     typing: DflowDataType | DflowDataType[] = [],

docs/examples/README.md

@@ -1,6 +1,11 @@
 # dflow examples
 
-First do steps in [this Requirements section](../../.github/CONTRIBUTING.md).
+First you need dflow.js bundle in the package root folder. You can build it with something like:
+
+```sh
+npm install esbuild --no-save
+npm run esbuild
+```
 
 Then you can run examples via an npm script:
 

docs/snippets/helloWorld.ts docs/examples/snippets/hello_world.tsdocs/snippets/helloWorld.ts renamed to docs/examples/snippets/hello_world.ts

@@ -207,10 +207,10 @@ <h2>API</h2>
       <h3 id="constructor">Constructor</h3>
 
       <p>
-      <code>Dflow</code> constructor requires a list of node definitions.
+      <code>Dflow</code> constructor requires a list of node definitions which is an <code>Array<<a href="#dflownode">DflowNode</a>></code>.
       </p>
 
-<!-- START file:docs/snippets/helloWorld.ts -->
+<!-- START file:docs/examples/snippets/helloWorld.ts -->
       <pre><code>
 import { Dflow, type DflowNode } from "dflow";
 
@@ -229,7 +229,7 @@ <h3 id="constructor">Constructor</h3>
 // Run the dflow graph.
 dflow.run()
       </code></pre>
-<!-- END file:docs/snippets/helloWorld.ts -->
+<!-- END file:docs/examples/snippets/helloWorld.ts -->
 
       <h3 id="methods">Methods</h3>
 
@@ -308,20 +308,20 @@ <h4>dflow.out</h4>
 
       <h3 id="static-methods">Static methods</h3>
 
-      <h4>Dflow.input()</h4>
+      <h4 id="dflow.input">Dflow.input()</h4>
 
       <p class="description">
       Helper to define inputs.
       </p>
 
-      <h4>Dflow.output()</h4>
+      <h4 id="dflow.output">Dflow.output()</h4>
 
       <p class="description">
       Helper to define outputs.
       </p>
 
       <p>
-      Define an output named π (PI) for a constant node
+      Define an output named <code>π</code> (PI) for a constant node
       </p>
 
 <!-- ./examples/nodes/math.ts -->
@@ -370,6 +370,14 @@ <h4 id="dflowdatatype">DflowDataType</h4>
         <li><code>"object"</code></li>
       </ul>
 
+      <p>
+      Both <code>DflowInput</code> and <code>DflowOutput</code> have a <code>types: DflowDataType[]</code> attribute which is used to check if they can be connected.
+      </p>
+
+      <p>
+      A special case is when <code>types</code> is an empty array. In this case, the input or output can accept <strong>any</strong> data type.
+      </p>
+
       <h4 id="dflowinput">DflowInput</h4>
 
       <p>
@@ -407,7 +415,7 @@ <h4 id="dflowlink">DflowLink</h4>
       Connects two nodes in the graph.
       </p>
 
-      <h4>DflowNode</h4>
+      <h4 id="dflownode">DflowNode</h4>
 
       <p class="description">
       Defines a block of code: it can have inputs and outputs.

docs/index.html

@@ -75,8 +75,11 @@ h2 { font-size: 2.5rem; }
 h3 { font-size: 2rem; }
 h4, h5, h6 { font-size: 1.5rem; }
 
-p {
+p, dl {
   max-width: 71ch;
+}
+
+p {
   line-height: 1.7;
   margin: var(--margin-text);
 }
@@ -159,7 +162,7 @@ ul {
 
 
 footer {
-  margin-top: 5rem;
+  margin-top: 25vh;
   font-size: 0.75em;
   padding: 2rem 1rem;
   background: #f8e0b5;

docs/style.css

@@ -18,7 +18,7 @@
     "esbuild": "esbuild dflow.ts --minify --outfile=dflow.js",
     "example:async_nodes": "node docs/examples/async_nodes.ts",
     "example:context": "node docs/examples/context.ts",
-    "example:hello_world": "node docs/examples/hello_world.ts",
+    "example:hello_world": "node docs/examples/snippets/hello_world.ts",
     "example:usage": "node docs/examples/usage.ts",
     "install_precommit_hook": "echo '#!/bin/sh\nnpm test && npm run prettier--check && npm run build\n' > .git/hooks/pre-commit; chmod +x .git/hooks/pre-commit",
     "prettier": "prettier --write .",