Add source documentation

backend/config/config.exs

@@ -16,6 +16,7 @@ config :azimutt,
   logo_url_for_emails: "https://azimutt.app/android-chrome-512x512.png",
   cli_url: "https://www.npmjs.com/package/azimutt",
   heroku_url: "https://elements.heroku.com/addons/azimutt",
+  npm_aml_url: "https://www.npmjs.com/package/@azimutt/aml",
   vscode_extension_url: "https://marketplace.visualstudio.com/items?itemName=azimutt.vscode-aml",
   browser_extension_url: "https://chrome.google.com/webstore/detail/azimutt/bpifdkechgdibghkkpaioccoijeoebjf",
   azimutt_documentation: "https://azimutt.app/docs",

backend/lib/azimutt_web/templates/website/aml.html.heex

@@ -1,6 +1,6 @@
 <%
   aml_doc = Routes.website_path(@conn, :doc, ["aml"])
-  aml_npm = "https://www.npmjs.com/package/@azimutt/aml"
+  aml_npm = Azimutt.config(:npm_aml_url)
   aml_vscode = Azimutt.config(:vscode_extension_url)
   aml_converter = Routes.website_path(@conn, :converter, "aml")
   aml_azimutt = Routes.elm_path(@conn, :create)

backend/lib/azimutt_web/templates/website/comparisons/dbml.html.heex

@@ -216,7 +216,7 @@ console.log('database', database)</code></pre>
 
     <%= render "docs/_h3.html", title: "AML tooling" %>
     <p>
-        AML package is <a href="https://www.npmjs.com/package/@azimutt/aml" target="_blank" rel="noopener">@azimutt/aml</a>,
+        AML package is <a href={Azimutt.config(:npm_aml_url)} target="_blank" rel="noopener">@azimutt/aml</a>,
         here is how to parse/generate AML into <a href="https://github.com/azimuttapp/azimutt/blob/main/libs/models/src/database.ts" target="_blank" rel="noopener">JSON</a>:
     </p>
     <pre><code class="hljs ts">import {generateAml, parseAml} from "@azimutt/aml"

backend/lib/azimutt_web/templates/website/converters/_description-short.html.heex

@@ -1,7 +1,7 @@
 <%= cond do %>
     <% @converter == "aml" -> %>
         A very simple language made by Azimutt to ease and speed database design.
-        In addition, you can use <a href={Routes.website_path(@conn, :aml)} class="underline">AML</a> inside Azimutt or as a <a href="https://www.npmjs.com/package/@azimutt/aml" target="_blank" rel="noopener noreferrer" class="underline">standalone library</a> for your own projects.
+        In addition, you can use <a href={Routes.website_path(@conn, :aml)} class="underline">AML</a> inside Azimutt or as a <a href={Azimutt.config(:npm_aml_url)} target="_blank" rel="noopener noreferrer" class="underline">standalone library</a> for your own projects.
     <% @converter == "dbml" -> %>
         <a href="https://github.com/holistics/dbml" target="_blank" rel="noopener noreferrer" class="underline">DBML</a> is a DSL made by <a href="https://www.holistics.io" target="_blank" rel="noopener noreferrer" class="underline">Holistics</a> to define and document database schemas and structures.
         It's used on <a href="https://dbdiagram.io" target="_blank" rel="noopener noreferrer" class="underline">dbdiagram.io</a>, an Entity-Relationship Diagram tool.

backend/lib/azimutt_web/templates/website/docs/aml.html.heex

@@ -5,7 +5,7 @@
     <p class="text-center">
         <a href={Routes.website_path(@conn, :aml)}>Home page</a> •
         <a href={Routes.website_path(@conn, :converter, "aml")}>Converter</a> •
-        <a href="https://www.npmjs.com/package/@azimutt/aml" target="_blank" rel="noopener noreferrer">npm package</a>
+        <a href={Azimutt.config(:npm_aml_url)} target="_blank" rel="noopener noreferrer">npm package</a>
     </p>
 
     <p class="lead">

backend/lib/azimutt_web/templates/website/docs/api.html.heex

@@ -5,6 +5,7 @@
 
     <%= render "docs/_h2.html", title: "HTTP API" %>
     <p class="lead">Work In Progress 😅</p>
+    <p>See <a href="/api/v1/swagger" target="_blank" rel="noopener">Swagger spec</a>.</p>
 
     <%= render "docs/_h3.html", title: "Source schema" %>
     <p class="lead">Work In Progress 😅</p>
@@ -14,6 +15,7 @@
 
     <%= render "docs/_h2.html", title: "JavaScript API" %>
     <p class="lead">Work In Progress 😅</p>
+    <p>On a project, open your JavaScript console a look at <code>azimutt</code> global value.</p>
 <% end %>
 
 <%= render "docs/_footer.html", conn: @conn, page: @page, prev: @prev, next: @next %>

backend/lib/azimutt_web/templates/website/docs/badge.html.heex

@@ -17,31 +17,31 @@
     </p>
     <ol>
         <li>
-            <p><strong>Navigate to your SQL schema file and get it's *raw* url</strong></p>
+            <p><b>Navigate to your SQL schema file and get it's *raw* url</b></p>
             <p>
-                For Azimutt the file is <a href="https://github.com/azimuttapp/azimutt/blob/main/backend/priv/repo/structure.sql" target="_blank" rel="noopener">backend/priv/repo/structure.sql</a>,
-                so the raw url is <i>https://raw.githubusercontent.com/azimuttapp/azimutt/refs/heads/main/backend/priv/repo/structure.sql</i>
+                For Azimutt the file is <a href="https://github.com/azimuttapp/azimutt/blob/main/backend/priv/repo/structure.sql" target="_blank" rel="noopener">backend/priv/repo/structure.sql</a>, so the raw url is:<br>
+                <i class="whitespace-nowrap">https://raw.githubusercontent.com/azimuttapp/azimutt/refs/heads/main/backend/priv/repo/structure.sql</i>
             </p>
         </li>
         <li>
-            <p><strong>Build the Azimutt create url</strong></p>
+            <p><b>Build the Azimutt create url</b></p>
             <p>
-                The structure is <code>https://azimutt.app/create?sql=$file_url&name=$project_name</code>, so Azimutt it's
-                <i>https://azimutt.app/create?sql=https://raw.githubusercontent.com/azimuttapp/azimutt/refs/heads/main/backend/priv/repo/structure.sql&name=Azimutt</i>
+                The format is <code>https://azimutt.app/create?sql=$url&name=$project_name</code>, so for Azimutt it's:<br>
+                <i class="whitespace-nowrap">https://azimutt.app/create?sql=https://raw.githubusercontent.com/azimuttapp/azimutt/refs/heads/main/backend/priv/repo/structure.sql&name=Azimutt</i>
             </p>
         </li>
         <li>
-            <p><strong>Create your badge with <a href="https://shields.io" target="_blank" rel="noopener">shields.io</a></strong></p>
+            <p><b>Create your badge with <a href="https://shields.io" target="_blank" rel="noopener">shields.io</a></b></p>
             <p>
-                You can build the ones you want. For PostgreSQL here is the suggested url:
-                <i>https://img.shields.io/badge/PostgreSQL-browse_online-gray?labelColor=4169E1&logo=postgresql&logoColor=fff&style=flat</i>.
+                You can build the one you want. For PostgreSQL here what we suggest:<br>
+                <i class="whitespace-nowrap">https://img.shields.io/badge/PostgreSQL-browse_online-gray?labelColor=4169E1&logo=postgresql&logoColor=fff&style=flat</i><br>
                 See below for others.
             </p>
         </li>
         <li>
-            <p><strong>Put everything together, displaying a link with image in your README</strong></p>
+            <p><b>Put everything together, displaying a link with image in your README</b></p>
             <p>
-                Here is how to do it in markdown: <code>[![Image alt](Image url)](Link url)</code>, so the final result for Azimutt is:
+                In Markdown it's: <code>[![Image alt](Image url)](Link url)</code>, so the final result for Azimutt is:<br>
                 <i>[![Explore database with Azimutt](https://img.shields.io/badge/PostgreSQL-browse_online-gray?labelColor=4169E1&logo=postgresql&logoColor=fff&style=flat)](https://azimutt.app/create?sql=https://raw.githubusercontent.com/azimuttapp/azimutt/refs/heads/main/backend/priv/repo/structure.sql&name=Azimutt)</i>
             </p>
         </li>

backend/lib/azimutt_web/templates/website/docs/create-your-project.html.heex

@@ -46,7 +46,7 @@
     <%= render "docs/_h2.html", title: "From Prisma" %>
     <p>
         <a href="https://www.prisma.io" target="_blank" rel="noopener noreferrer" class="underline">Prisma</a> is a Node.js and TypeScript ORM
-        that use its own <a href="https://www.prisma.io/docs/orm/prisma-schema" target="_blank" rel="noopener noreferrer" class="underline">schema syntax</a>.
+        that use its own <a href="https://www.prisma.io/docs/orm/prisma-schema/overview" target="_blank" rel="noopener noreferrer" class="underline">schema syntax</a>.
         Same as SQL, you can import the file in Azimutt, local or remote.
     </p>
 
@@ -65,7 +65,7 @@
         If you are looking to design your database, and not explore an existing one.<br>
         You can <a href={"#{Routes.elm_path(@conn, :create)}?aml"} target="_blank" rel="noopener noreferrer">create an empty project</a>
         and use <a href={Routes.website_path(@conn, :aml)}>AML</a> to design it.<br>
-        You can always add other sources from any kind after with the Azimutt <a href={"#{Routes.website_path(@conn, :doc, ["sources"])}#multi-sources"}>multi-source feature</a>.
+        You can always add other sources from any kind after with the Azimutt <a href={Routes.website_path(@conn, :doc, ["sources"])}>multi-source feature</a>.
     </p>
 
     <%= render "docs/_h2.html", title: "Import project" %>

backend/lib/azimutt_web/templates/website/docs/data-exploration.html.heex

@@ -2,6 +2,13 @@
 
 <%= doc_prose do %>
     <p class="lead">Work In Progress 😅</p>
+    <!-- <p class="lead">
+        Azimutt started as a database schema explorer, and it's probably still the first part you can see from it.
+        But it has evolved into a complete toolset for real world databases, with documentation, data exploration and even suggests database improvements.
+    </p>
+    <p>
+        Of course, the data exploration needs a real database connection to be used.
+    </p> -->
 
     <%= render "docs/_h2.html", title: "Data statistics" %>
     <%= render "docs/_h2.html", title: "SQL query" %>

backend/lib/azimutt_web/templates/website/docs/documentation.html.heex

@@ -30,7 +30,7 @@
             </ul>
         </li>
         <li>
-            <a href="#layout-documentation">Layout documentation</a>: for specific parts or use cases, even <a href={"#{Routes.website_path(@conn, :doc, ["sources"])}#multi-sources"}>cross-database</a> ^^
+            <a href="#layout-documentation">Layout documentation</a>: for specific parts or use cases, even <a href={Routes.website_path(@conn, :doc, ["sources"])}>cross-database</a> ^^
             <ul>
                 <li><a href="#layout-hierarchy">Layout hierarchy</a></li>
                 <li><a href="#color">Color</a></li>
@@ -41,7 +41,7 @@
     </ul>
     <p>
         Of course, this documentation is not locked inside Azimutt.
-        It's accessible with the <a href="/api/v1/swagger" target="_blank" rel="noopener">API</a> so you can sync Azimutt with anything else, as a source or a destination, once or periodically.
+        It's accessible with the <a href={"#{Routes.website_path(@conn, :doc, ["api"])}#http-api"}>API</a> so you can sync Azimutt with anything else, as a source or a destination, once or periodically.
     </p>
 
     <%= render "docs/_h2.html", title: "Schema documentation" %>