NeTEx: Documentation en ligne des règles France (#5461)

Author: ptitfred

apps/transport/client/stylesheets/components/_validation.scss

@@ -124,60 +124,76 @@ details > code {
   }
 }
 
-table.netex_generic_issue, table.netex_xsd_schema {
-  tr.message td {
-    vertical-align: top;
+.download-button {
+  text-decoration: none;
+  &:hover {
+    background-color: unset;
   }
 }
 
-table.netex_generic_issue {
-  th, td {
-    &:nth-child(1) {
-      width: 60%;
-    }
-    &:nth-child(3) {
-      width: 10%;
+.netex {
+  dialog.inline-help {
+    max-width: 90%;
+    width: 80ch;
+    max-height: 90%;
+    overflow: scrollable;
+    overscroll-behavior: contain;
+
+    h5 { margin-block: 0 1em; }
+    h6 { margin-block: 2em 1em; }
+    .header_with_action_bar + h6 { margin-top: 0; }
+    .fa-close { padding: unset }
+    code { font-size: 0.75em; }
+  }
+
+  table.netex_generic_issue, table.netex_xsd_schema {
+    tr.message td {
+      vertical-align: top;
     }
   }
-}
 
-table.netex_xsd_schema {
-  tr, td {
-    &:nth-child(1) {
-      text-align: right;
+  table.netex_xsd_schema {
+    tr, td {
+      &:nth-child(1) {
+        text-align: right;
+      }
     }
   }
-}
 
-table.netex_generic_issue tr.debug:hover {
-  background: revert;
-}
+  table.netex_generic_issue {
+    th, td {
+      &:nth-child(1) {
+        width: 60%;
+      }
+      &:nth-child(3) {
+        width: 10%;
+      }
+    }
 
-table.netex_generic_issue tr.debug td {
-  border-top: none;
-  padding-top: 0;
-}
+    tr.debug {
+      &:hover {
+        background: revert;
+      }
 
-table.netex_generic_issue tr.debug td summary {
-  cursor: pointer;
-}
+      td {
+        border-top: none;
+        padding-top: 0;
 
-table.netex_generic_issue tr.debug td pre {
-  margin-block: 0;
-}
+        summary {
+          cursor: pointer;
+        }
 
-table.netex_generic_issue tr.debug td code {
-  width: 100%;
-}
+        pre {
+          margin-block: 0;
+        }
 
-.download-button {
-  text-decoration: none;
-  &:hover {
-    background-color: unset;
+        code {
+          width: 100%;
+        }
+      }
+    }
   }
-}
 
-.netex {
   #download-popup {
     max-width: 60ch;
 
@@ -278,6 +294,10 @@ table.netex_generic_issue tr.debug td code {
       --taint: var(--orange);
     }
   }
+
+  button[popovertarget="french-profile-rules"] {
+    margin-left: 0.5em;
+  }
 }
 
 blockquote {

apps/transport/lib/netex/chouette_valid_ruleset_generator.ex

@@ -9,6 +9,8 @@ defmodule Transport.NeTEx.ChouetteValidRulesetGenerator do
   - it can keep track of source documentation for each rule to help maintain a user friendly interface
   """
 
+  use Gettext, backend: TransportWeb.Gettext
+
   def mandatory_attributes(parent, names, documentation_title, documentation_url) do
     %{
       type: :mandatory_attributes,
@@ -31,27 +33,42 @@ defmodule Transport.NeTEx.ChouetteValidRulesetGenerator do
     Enum.map(ruleset, &process_rule_context(sub_profile, &1))
   end
 
-  def document_ruleset(ruleset, device \\ :stdio) do
-    Enum.each(ruleset, &document_sub_profile(&1, device))
+  def document_ruleset(ruleset, device \\ :stdio, markdown_options \\ []) do
+    Enum.each(ruleset, &document_sub_profile(&1, device, markdown_options))
   end
 
-  def document_sub_profile(%{title: title, ruleset: ruleset}, device) do
-    IO.puts(device, "## #{title}")
-    IO.puts(device, "")
+  def document_sub_profile(%{title: title, ruleset: ruleset}, device, options) do
+    header_level = Keyword.get(options, :header_level, 1)
 
-    ruleset
-    |> Enum.each(fn rule_context ->
-      IO.puts(device, "In [#{rule_context.documentation_link.title}](#{rule_context.documentation_link.url}):")
+    if not Enum.empty?(ruleset) do
+      IO.puts(device, header(header_level, dgettext("netex-documentation", "Sub-profile “%{title}”", title: title)))
       IO.puts(device, "")
 
-      for name <- rule_context.names do
-        IO.puts(device, "- `//#{rule_context.parent}/#{name}` : `0:1` -> `1:1`")
-      end
+      ruleset
+      |> Enum.each(fn rule_context ->
+        IO.puts(device, dgettext("netex-documentation", "Section [%{title}](%{url}):", rule_context.documentation_link))
+        IO.puts(device, "")
+
+        for name <- rule_context.names do
+          IO.puts(
+            device,
+            "- #{dgettext("netex-documentation", "The element `%{name}` is required.", name: "#{rule_context.parent}/#{name}")}"
+          )
+        end
+
+        IO.puts(device, "")
+      end)
+    end
+  end
 
-      IO.puts(device, "")
-    end)
+  defp header(level, text) when level in 1..6 do
+    symbol = "######" |> String.slice(0, level)
+
+    "#{symbol} #{text}"
   end
 
+  defp header(_level, text), do: text
+
   def process_rule_context(sub_profile, %{type: :mandatory_attributes, parent: parent, names: names}) do
     %{
       rule_context: "resource/kind_of",

apps/transport/lib/netex/french_profile.ex

@@ -13,5 +13,5 @@ defmodule Transport.NeTEx.FrenchProfile do
 
   defdelegate slug, to: Latest
   defdelegate ruleset(device), to: Latest
-  defdelegate markdown(device), to: Latest
+  defdelegate markdown(device, markdown_options), to: Latest
 end

apps/transport/lib/netex/french_profile/v1.ex

@@ -17,8 +17,8 @@ defmodule Transport.NeTEx.FrenchProfile.V1 do
     definition() |> encode_ruleset(device)
   end
 
-  def markdown(device \\ :stdio) do
-    definition() |> document_ruleset(device)
+  def markdown(device \\ :stdio, markdown_options \\ []) do
+    definition() |> document_ruleset(device, markdown_options)
   end
 
   defp definition do

apps/transport/lib/netex/french_profile/v2.ex

@@ -19,8 +19,8 @@ defmodule Transport.NeTEx.FrenchProfile.V2 do
     definition() |> encode_ruleset(device)
   end
 
-  def markdown(device \\ :stdio) do
-    definition() |> document_ruleset(device)
+  def markdown(device \\ :stdio, markdown_options \\ []) do
+    definition() |> document_ruleset(device, markdown_options)
   end
 
   defp definition do

apps/transport/lib/transport_web/views/netex_report_components.ex

@@ -105,6 +105,7 @@ defmodule TransportWeb.NeTExReportComponents do
       errors={errors}
       validation_report_url={@validation_report_url}
       pagination={@pagination}
+      results_adapter={@results_adapter}
     />
     """
   end
@@ -138,41 +139,55 @@ defmodule TransportWeb.NeTExReportComponents do
   end
 
   defp netex_validation_selected_category(
-         %{conn: _, compliance_check: _, current_category: _, errors: _, validation_report_url: _, pagination: _} =
+         %{
+           conn: _,
+           compliance_check: _,
+           current_category: _,
+           errors: _,
+           validation_report_url: _,
+           pagination: _,
+           results_adapter: _
+         } =
            assigns
        ) do
     ~H"""
     <% locale = get_session(@conn, :locale) %>
     <div class="selected-category">
-      <.netex_category_description category={@current_category} compliance_check={@compliance_check} conn={@conn} />
+      <.netex_category_description
+        category={@current_category}
+        compliance_check={@compliance_check}
+        conn={@conn}
+        results_adapter={@results_adapter}
+      />
       <.netex_category_comment count={Enum.count(@errors)} category={@current_category} />
 
-      <div :if={@current_category == "xsd-schema" and Enum.count(@errors) > 0} id="issues-list">
-        <p>
-          {dgettext(
-            "validations-explanations",
-            "Here is a summary of XSD validation errors. Full detail of those errors is available in the <a href=\"%{validation_report_url}\" target=\"_blank\">CSV report</a>. Those errors are produced by <a href=\"https://gnome.pages.gitlab.gnome.org/libxml2/xmllint.html\" target=\"_blank\">xmllint</a>.",
-            validation_report_url: @validation_report_url
-          )
-          |> raw()}
-        </p>
-        <.non_translated_messages locale={locale} />
-        <table class="table netex_xsd_schema">
-          <tr>
-            <th>{dgettext("validations-explanations", "Occurrences")}</th>
-            <th>{dgettext("validations-explanations", "Message")}</th>
-          </tr>
-
-          <tr :for={xsd_error <- @errors} class="message">
-            <td>{Helpers.format_number(xsd_error["counts"], locale: locale)}</td>
-            <td lang="en">{xsd_error["message"]}</td>
-          </tr>
-        </table>
-      </div>
-      <div :if={@current_category != "xsd-schema" and Enum.count(@errors) > 0} id="issues-list">
-        <.non_translated_messages locale={locale} />
-        <.netex_generic_issues issues={@errors} />
-        {@pagination}
+      <div :if={Enum.count(@errors) > 0} id="issues-list">
+        <%= if @current_category == "xsd-schema" do %>
+          <p>
+            {dgettext(
+              "validations-explanations",
+              "Here is a summary of XSD validation errors. Full detail of those errors is available in the <a href=\"%{validation_report_url}\" target=\"_blank\">CSV report</a>. Those errors are produced by <a href=\"https://gnome.pages.gitlab.gnome.org/libxml2/xmllint.html\" target=\"_blank\">xmllint</a>.",
+              validation_report_url: @validation_report_url
+            )
+            |> raw()}
+          </p>
+          <.non_translated_messages locale={locale} />
+          <table class="table netex_xsd_schema">
+            <tr>
+              <th>{dgettext("validations-explanations", "Occurrences")}</th>
+              <th>{dgettext("validations-explanations", "Message")}</th>
+            </tr>
+
+            <tr :for={xsd_error <- @errors} class="message">
+              <td>{Helpers.format_number(xsd_error["counts"], locale: locale)}</td>
+              <td lang="en">{xsd_error["message"]}</td>
+            </tr>
+          </table>
+        <% else %>
+          <.non_translated_messages locale={locale} />
+          <.netex_generic_issues issues={@errors} />
+          {@pagination}
+        <% end %>
       </div>
     </div>
     """
@@ -259,11 +274,33 @@ defmodule TransportWeb.NeTExReportComponents do
     """
   end
 
-  defp netex_category_tooltip(%{category: _, compliance_check: _} = assigns) do
+  defp with_string(proc) do
+    {:ok, device} = StringIO.open("")
+
+    proc.(device)
+
+    StringIO.flush(device)
+  end
+
+  defp netex_category_tooltip(%{category: _, compliance_check: _, results_adapter: _, conn: _} = assigns) do
     ~H"""
+    <% french_profile = @results_adapter.french_profile() %>
     <p :if={@category == "french-profile"}>
       <.info_icon /> {french_profile_comment(@compliance_check)}
+      <button :if={french_profile} class="button-outline small secondary" popovertarget="french-profile-rules">
+        <i class="fa fa-circle-question" aria-hidden="true"></i> {dgettext("validations", "Learn more")}
+      </button>
     </p>
+    <dialog :if={french_profile} id="french-profile-rules" popover class="panel inline-help">
+      <div class="header_with_action_bar">
+        <h5>{dgettext("validations", "List of French Profile rules currently checked")}</h5>
+        <button popovertarget="french-profile-rules" popovertargetaction="hide" class="small secondary">
+          <i class="fa fa-close"></i>
+        </button>
+      </div>
+      <% markdown = with_string(&french_profile.markdown(&1, header_level: 6)) %>
+      {markdown_to_safe_html!(markdown)}
+    </dialog>
     """
   end
 
@@ -272,6 +309,23 @@ defmodule TransportWeb.NeTExReportComponents do
     """
   end
 
+  defp markdown_to_safe_html!(markdown) do
+    case TransportWeb.MarkdownHandler.markdown_to_safe_html!(markdown) do
+      {:safe, safe} -> {:safe, update_links_target(safe)}
+      otherwise -> otherwise
+    end
+  end
+
+  defp update_links_target(html) do
+    html
+    |> Floki.parse_fragment!()
+    |> Floki.traverse_and_update(fn
+      {"a", attrs, children} -> {"a", [{"target", "_blank"} | attrs], children}
+      other -> other
+    end)
+    |> Floki.raw_html()
+  end
+
   defp french_profile_comment(:none), do: dgettext("validations", "netex-french-profile-no-compliance") |> raw()
   defp french_profile_comment(:partial), do: dgettext("validations", "netex-french-profile-partial-compliance") |> raw()
   defp french_profile_comment(:good_enough), do: ""
@@ -309,14 +363,19 @@ defmodule TransportWeb.NeTExReportComponents do
     Map.reject(query_params, fn {_, v} -> is_nil(v) end)
   end
 
-  defp netex_category_description(%{category: _, compliance_check: _, conn: _} = assigns) do
+  defp netex_category_description(%{category: _, compliance_check: _, conn: _, results_adapter: _} = assigns) do
     ~H"""
     <% url = netex_link_to_category(@conn, "french-profile") %>
     <% description = netex_category_description_html(@category, url) %>
     <p :if={description}>
       {raw(description)}
     </p>
-    <.netex_category_tooltip category={@category} compliance_check={@compliance_check} />
+    <.netex_category_tooltip
+      category={@category}
+      compliance_check={@compliance_check}
+      results_adapter={@results_adapter}
+      conn={@conn}
+    />
     """
   end