feat: add docs pages

config/dev.exs

@@ -61,6 +61,7 @@ config :admin, AdminWeb.Endpoint,
       ~r"priv/gettext/.*(po)$",
       ~r"priv/blog/.*(md)$",
       ~r"priv/pages/.*(md)$",
+      ~r"priv/docs/.*(md)$",
       ~r"lib/admin_web/(?:controllers|live|components|router)/?.*\.(ex|heex)$"
     ]
   ]

lib/admin/docs.ex

@@ -0,0 +1,50 @@
+defmodule Admin.Docs do
+  @moduledoc """
+  Module for publishing documentation pages.
+  """
+
+  alias Admin.Docs.Page
+
+  use NimblePublisher,
+    build: Page,
+    from: Application.app_dir(:admin, "priv/docs/**/*.md"),
+    as: :pages
+
+  use Admin.Docs.Sections, path: "priv/docs/en"
+
+  @pages Enum.sort_by(@pages, &(&1.order || 1000), :asc)
+
+  def all_pages, do: @pages
+
+  def all_ids,
+    do: for_locale("en") |> Enum.map(& &1.id) |> Enum.uniq()
+
+  def for_locale("en"), do: all_pages() |> Enum.filter(&(&1.locale == "en"))
+
+  def for_locale(locale) do
+    for_locale("en")
+    |> Enum.map(fn page ->
+      Enum.find(all_pages(), &(&1.id == page.id and &1.locale == locale)) || page
+    end)
+  end
+
+  def for_locale_by_sections(locale),
+    do: for_locale(locale) |> Enum.group_by(& &1.section)
+
+  def with_tag(tag, locale),
+    do: for_locale(locale) |> Enum.filter(&(tag in &1.tags))
+
+  def all_topics do
+    all_pages() |> Enum.map(& &1.section) |> Enum.uniq()
+  end
+
+  def all_sections do
+    @pages
+    |> Enum.group_by(fn page -> page.section end)
+  end
+
+  def get_page_by_id!(id) do
+    Enum.find(@pages, fn post -> post.id == id end) ||
+      raise AdminWeb.NotFoundError, "page with id=#{id} not found"
+  end
+end

lib/admin/docs/page.ex

@@ -0,0 +1,31 @@
+defmodule Admin.Docs.Page do
+  @moduledoc """
+  A module that represents a documentation page.
+  """
+
+  @enforce_keys [:id, :locale, :section, :title, :body, :description, :tags, :order]
+  defstruct [:id, :locale, :section, :title, :body, :description, :tags, :order]
+
+  def build(filename, attrs, body) do
+    [locale, section, id] = filename |> Path.rootname() |> Path.split() |> Enum.take(-3)
+
+    [locale, section, id] =
+      case locale do
+        "docs" -> [section, "", id]
+        _ -> [locale, section, id]
+      end
+
+    struct!(
+      __MODULE__,
+      id: id,
+      locale: locale,
+      section: section,
+      body: body,
+      title: attrs[:title] || "",
+      body: body,
+      description: attrs[:description] || "",
+      tags: attrs[:tags] || [],
+      order: attrs[:order] || 1000
+    )
+  end
+end

lib/admin/docs/sections.ex

@@ -0,0 +1,31 @@
+defmodule Admin.Docs.Sections do
+  @moduledoc """
+  Define translation strings from the name of the folders in the application folder
+  """
+
+  defmacro __using__(opts) do
+    path = Keyword.fetch!(opts, :path)
+
+    folder_names =
+      File.ls!(path)
+      |> Enum.filter(fn name ->
+        File.dir?(Path.join(path, name))
+      end)
+
+    quote bind_quoted: [folders: folder_names] do
+      use Gettext, backend: AdminWeb.Gettext
+
+      # For each folder, we generate a clause that calls dgettext/2
+      for folder <- folders do
+        def translate_section(unquote(folder)) do
+          # This *literal* is what gettext.extract sees
+          pgettext("documentation section", unquote(folder))
+        end
+      end
+
+      def translate_section("") do
+        pgettext("documentation section", "Introduction")
+      end
+    end
+  end
+end

lib/admin_web/components/layouts.ex

@@ -309,6 +309,9 @@ defmodule AdminWeb.Layouts do
               <li>
                 <.link navigate={~p"/blog"}>{gettext("Blog")}</.link>
               </li>
+              <li>
+                <.link navigate={~p"/docs"}>{gettext("Documentation")}</.link>
+              </li>
               <li>
                 <.link navigate={~p"/about-us"}>{gettext("About")}</.link>
               </li>
@@ -342,6 +345,9 @@ defmodule AdminWeb.Layouts do
           <ul class="menu menu-horizontal px-1">
             <li><.link class="text-primary" navigate={~p"/library"}>{gettext("Library")}</.link></li>
             <li><.link class="text-primary" navigate={~p"/blog"}>{gettext("Blog")}</.link></li>
+            <li>
+              <.link class="text-primary" navigate={~p"/docs"}>{gettext("Documentation")}</.link>
+            </li>
             <li><.link class="text-primary" navigate={~p"/about-us"}>{gettext("About")}</.link></li>
             <li><.link class="text-primary" navigate={~p"/contact"}>{gettext("Contact")}</.link></li>
             <%= if @current_scope do %>

lib/admin_web/controllers/docs_controller.ex

@@ -0,0 +1,41 @@
+defmodule AdminWeb.DocsController do
+  use AdminWeb, :controller
+
+  alias Admin.Docs
+
+  def index(conn, %{"tag" => tag}) do
+    pages = Docs.with_tag(tag, conn.assigns[:locale])
+
+    render(conn, :search,
+      page_title: pgettext("page_title", "Search Documentation"),
+      tag: tag,
+      pages: pages
+    )
+  end
+
+  def index(conn, _params) do
+    sections = Docs.for_locale_by_sections(conn.assigns[:locale])
+    {%{"" => intro}, sections} = Map.split(sections, [""])
+
+    render(conn, :index,
+      page_title: pgettext("page_title", "Documentation"),
+      page_description:
+        pgettext(
+          "page_description",
+          "The documentation for the Graasp products and services."
+        ),
+      intro: intro,
+      sections: sections
+    )
+  end
+
+  def show(conn, %{"id" => id}) do
+    page = Docs.get_page_by_id!(id)
+
+    render(conn, :show,
+      page_title: page.title,
+      page_description: page.description,
+      page: page
+    )
+  end
+end

lib/admin_web/controllers/docs_html.ex

@@ -0,0 +1,4 @@
+defmodule AdminWeb.DocsHTML do
+  use AdminWeb, :html
+  embed_templates "docs_html/*"
+end

lib/admin_web/controllers/docs_html/index.html.heex

@@ -0,0 +1,56 @@
+<Layouts.landing flash={@flash} current_scope={@current_scope} locale_form={@locale_form}>
+  <div class="flex flex-col gap-4 p-10 max-w-screen-lg mx-auto">
+    <h1 class="text-3xl font-semibold text-primary">{gettext("Documentation")}</h1>
+    <p class="text-base">
+      {gettext(
+        "Welcome to the documentation page. Here you can find information about our products and services."
+      )}
+    </p>
+    <div class="flex flex-row p-4 gap-8">
+      <div class="flex flex-col gap-4 grow">
+        <article id="intro" class="flex flex-col gap-4 bg-base-100 p-6 rounded-lg">
+          <h2 class="text-2xl font-semibold text-primary">
+            {Admin.Docs.translate_section("")}
+          </h2>
+          <%= for page <- @intro do %>
+            <div class="flex flex-col">
+              <.link href={~p"/docs/#{page.id}"}>
+                {page.title}
+                <span
+                  :if={page.locale != Gettext.get_locale()}
+                  class="badge badge-outline badge-neutral badge-xs align-top"
+                >
+                  {page.locale}
+                </span>
+              </.link>
+              <span class="text-sm text-neutral">{page.description}</span>
+            </div>
+          <% end %>
+        </article>
+        <div class="grid grid-cols-1 sm:grid-cols-2 gap-4 wrap">
+          <%= for {section, section_pages} <- @sections do %>
+            <article id={section} class="flex flex-col gap-4 bg-base-100 p-6 rounded-lg">
+              <h2 class="text-2xl font-semibold text-primary">
+                {Admin.Docs.translate_section(section)}
+              </h2>
+              <%= for page <- section_pages do %>
+                <div class="flex flex-col">
+                  <.link href={~p"/docs/#{page.id}"}>
+                    {page.title}
+                    <span
+                      :if={page.locale != Gettext.get_locale()}
+                      class="badge badge-outline badge-neutral badge-xs align-top"
+                    >
+                      {page.locale}
+                    </span>
+                  </.link>
+                  <span class="text-sm text-neutral">{page.description}</span>
+                </div>
+              <% end %>
+            </article>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  </div>
+</Layouts.landing>

lib/admin_web/controllers/docs_html/search.html.heex

@@ -0,0 +1,27 @@
+<Layouts.landing flash={@flash} current_scope={@current_scope} locale_form={@locale_form}>
+  <div class="flex flex-col gap-4 p-10 max-w-screen-lg mx-auto">
+    <h1 class="text-3xl font-semibold text-primary">
+      {gettext("Search documentation for %{tag}", tag: @tag)}
+    </h1>
+    <p class="text-base">
+      {gettext(
+        "Welcome to the documentation page. Here you can find information about our products and services."
+      )}
+    </p>
+    <div class="flex flex-row p-4 gap-8">
+      <div class="flex flex-col gap-2 grow">
+        <div class="grid grid-cols-1 sm:grid-cols-2 gap-4 wrap px-2">
+          <%= for page <- @pages do %>
+            <.link
+              href={~p"/docs/#{page.id}"}
+              class="flex flex-col p-4 bg-base-100 rounded-lg grow hover:shadow-md"
+            >
+              <span>{page.title}</span>
+              <span class="text-sm text-neutral">{page.description}</span>
+            </.link>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  </div>
+</Layouts.landing>

lib/admin_web/controllers/docs_html/show.html.heex

@@ -0,0 +1,48 @@
+<Layouts.landing flash={@flash} current_scope={@current_scope} locale_form={@locale_form}>
+  <div class="flex flex-row gap-4 p-10 max-w-screen-xl mx-auto">
+    <nav class="flex flex-col gap-4 wrap px-2 flex-1 w-full min-w-[180px] shrink-0 hidden md:flex">
+      <h2 class="text-xl font-semibold">{gettext("Documentation")}</h2>
+      <div class="flex flex-col gap-4">
+        <%= for {section, pages} <- Admin.Docs.for_locale_by_sections(Gettext.get_locale()) do %>
+          <div>
+            <span class="text-primary">{Admin.Docs.translate_section(section)}</span>
+            <div class="gap-1 flex flex-col">
+              <%= for page <- pages do %>
+                <.link
+                  class={[
+                    "ps-4 link",
+                    if(page.id == @page.id, do: "font-bold", else: "link-hover")
+                  ]}
+                  href={~p"/docs/#{page.id}"}
+                >
+                  {page.title}
+                  <span
+                    :if={page.locale != Gettext.get_locale()}
+                    class="badge badge-outline badge-xs"
+                  >
+                    {page.locale}
+                  </span>
+                </.link>
+              <% end %>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    </nav>
+    <div class="flex flex-col gap-2 align-start flex-5 max-w-screen-md mx-auto ">
+      <.link class="btn btn-ghost w-fit" href={~p"/docs"}>
+        <.icon name="hero-arrow-left" /> {gettext("Back to documentation")}
+      </.link>
+      <article class="flex flex-col bg-base-100 py-8 px-12 rounded-lg w-full h-full">
+        <h1 class="text-4xl font-bold text-primary mb-4">{@page.title}</h1>
+        <div class="flex flex-row gap-1">
+          <.link :for={tag <- @page.tags} class="badge badge-primary" href={~p"/docs/?tag=#{tag}"}>
+            {tag}
+          </.link>
+        </div>
+        <p class="text-gray-400 text-sm mb-4"></p>
+        <div class="prose">{raw(@page.body)}</div>
+      </article>
+    </div>
+  </div>
+</Layouts.landing>

lib/admin_web/router.ex

@@ -51,6 +51,11 @@ defmodule AdminWeb.Router do
       get "/:id", BlogController, :show
     end
 
+    scope "/docs" do
+      get "/", DocsController, :index
+      get "/:id", DocsController, :show
+    end
+
     # routes to test locale
     get "/locale", LandingController, :locale
     post "/locale", LandingController, :change_locale

priv/docs/en/account/account-validation.md

@@ -0,0 +1,30 @@
+%{
+title: "Account Validation",
+description: "How to validate your account",
+tags: ["account"],
+order: 40
+}
+
+---
+
+When you use the Graasp platform, a verified email address is required.
+
+The email address verification is required to create content, publish content in the library and more. Once you have verified your email address you will be able to use all features of the platform.
+
+## When you see the "Your account needs to be validated" message
+
+If you see the message "Your account needs to be validated" (see the image bellow) it means we still need to validate that you have access to the **email address** you provided when you created your Graasp account.
+
+## How to validate my account? {: #validate-account}
+
+To validate your account you need to:
+
+1. Check which email you use with your Graasp account.
+2. Ensure you have access to this email.
+   1. If you do not have access to this email anymore, [change your email](account-email#change-email).
+3. Use that email to [login via email](login#login-email).
+4. Your account will be validated when you use the link we send you by email.
+
+> #### How to change your email {: .info}
+>
+> If you wish to change the email you use with your Graasp account, checkout [How to change the email used with my account](account-email#change-email).