Merge branch 'launch-documentation' into 'master'

feat: Add initial framework documentation

See merge request mythic-insight/legendary!50

.gitlab-ci.yml

@@ -1,5 +1,5 @@
 stages:
-  - application_dependencies
+  - prebuild
   - asset_dependencies
   - test
   - deploy_tags
@@ -15,11 +15,10 @@ variables:
   # fetch & clean the repo rather than completely cloning (faster)
   GIT_STRATEGY: fetch
 
-# Dependency stages-- fetch these first so that we can cache them and reuse them
+# Build the app once and cache it so that we can have fast compiles in test
-#   across jobs and pipelines. Note that elixir deps need to go first, because
+#   and Docker built steps
-#   we need the phoenix and phoenix_html hex packages to install their JS.
+prebuild:
-fetch_application_dependencies:
+  stage: prebuild
-  stage: application_dependencies
   image: "elixir:1.10"
   cache:
     key:
@@ -33,6 +32,7 @@ fetch_application_dependencies:
     - mix local.rebar --force
     - mix deps.get
     - mix deps.compile
+    - mix compile
   # Make results available to other jobs
   artifacts:
     paths:
@@ -45,7 +45,7 @@ fetch_asset_dependencies:
   stage: asset_dependencies
   image: "node:15.0"
   needs:
-    - fetch_application_dependencies
+    - prebuild
   only:
     - master
   cache:
@@ -68,7 +68,7 @@ fetch_asset_dependencies:
 test:
   stage: test
   needs:
-    - fetch_application_dependencies
+    - prebuild
   image: "elixir:1.10"
   services:
   - name: postgres:12
@@ -85,7 +85,7 @@ build_image_for_commit:
   stage: test
   needs:
     - fetch_asset_dependencies
-    - fetch_application_dependencies
+    - prebuild
   image: "docker:20.10"
   only:
     - master
@@ -99,6 +99,7 @@ build_image_for_commit:
       - _build/
       - deps/
   script:
+    - ls -la _build
     - docker login "https://${CI_REGISTRY}" -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
     - docker pull $CI_REGISTRY_IMAGE:latest || true
     # This enables fast parallel builds
@@ -109,6 +110,7 @@ build_image_for_commit:
     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
     # This copies the elixir build artifacts for deps and app so that we can cache them
     - docker cp `docker create $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA`:/root/app/_build/prod _build
+    - ls -la _build
 
 # If tests pass, tag the commit and update package versions
 deploy_to_tags:

apps/core/guides/features/admin.md

@@ -0,0 +1 @@
+# Admin

apps/core/guides/features/auth.md

@@ -0,0 +1 @@
+# Authentication and Authorization

apps/core/guides/features/background-jobs.md

@@ -0,0 +1 @@
+# Background Jobs

apps/core/guides/features/content-management.md

@@ -0,0 +1 @@
+# Content Management

apps/core/guides/features/devops-templates.md

@@ -0,0 +1 @@
+# DevOps Templates

apps/core/guides/features/fluid-email-templates.md

@@ -0,0 +1 @@
+# Fluid Email Templates

apps/core/guides/features/i18n.md

@@ -0,0 +1 @@
+# I18n

apps/core/guides/features/tasks-and-scripts.md

@@ -0,0 +1 @@
+# Tasks and Scripts

apps/core/guides/overview.md

@@ -23,6 +23,13 @@ development better.
 
 ## Up and Running
 
+Since Legendary is both a template and a framework, you can simply clone the repo
+to start using it. It's a fully functional Phoenix app as-is. To start a new project:
+
+```sh
+git clone git@gitlab.com:mythic-insight/legendary.git <project_name>
+```
+
 In order to start the server, run `script/server`. Any dependencies required
 will be installed automatically using [brew](https://brew.sh/),
 [asdf](https://asdf-vm.com/#/), and [hex](https://hex.pm/).
@@ -31,27 +38,31 @@ Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
 
 ## Development
 
-Your main app lives in apps/app/ and that is where you will do most of your
+Check out [the tutorial](tutorial.md) to learn how to build your first app with
+Legendary.
+
+Your main app lives in apps/app/ and you will do most of your
 development there. This is a normal Phoenix application and you can develop it
 as such. Any resources which apply to developing Phoenix applications will apply
 inside of the app. See the [Phoenix Guides](https://hexdocs.pm/phoenix/overview.html)
 for a good starting resource in Phoenix development.
 
 You should not generally need to change code in the other applications which
-are part of the framework-- admin, content, core. We encourage you to avoid
+are part of the framework-- apps/admin, apps/content, apps/core. We encourage you
-changing those as much as possible, because doing so will make it more difficult
+to avoid changing those as much as possible, because doing so will make it more
-to upgrade Legendary to newer versions. However, they are available to you if
+difficult to upgrade Legendary to newer versions. However, they are available to
-you find that there are no other ways to accomplish the changes you want to
+you if you find that there are no other ways to accomplish the changes that you want.
-accomplish. If you find yourself adding functionality to admin, content, or core
+If you find yourself adding functionality to admin, content, or core
 that you feel would be beneficial to all Legendary apps, consider making a
 code contribution back to the framework!
 
 ## CI Configuration
 
-Legendary comes with gitlab CI settings which should work for you with minimal
+Legendary comes with GitLab CI settings which should work for you with minimal
 setup.
 
 The CI script will automatically tag successful builds. To do this, you will
-need to configure a [CI variable](-/settings/ci_cd) named `GITLAB_TOKEN`. This
+need to configure a [CI variable](https://docs.gitlab.com/ee/ci/variables/) named
-token should be a [personal access token](/-/profile/personal_access_tokens) with
+`GITLAB_TOKEN`. This token should be a
+[personal access token](https://gitlab.com/-/profile/personal_access_tokens) with
 `read_repository, write_repository` permissions.

apps/core/guides/tutorial.md

@@ -0,0 +1 @@
+# Tutorial

apps/core/lib/core_web/views/helpers.ex

@@ -1,6 +1,6 @@
 defmodule Legendary.CoreWeb.Helpers do
   @moduledoc """
-  HTML helpers for our styled (Fomantic UI) forms.
+  HTML helpers for our styled (Tailwind) forms.
   """
   use Phoenix.HTML
 

apps/core/mix.exs

@@ -26,8 +26,10 @@ defmodule Legendary.Core.MixProject do
       homepage_url: "https://legendaryframework.org/",
       docs: [
         main: "overview",
-        extra_section: "GUIDES",
+        extra_section: "Getting Started",
-        extras: extras()
+        extras: extras(),
+        groups_for_extras: groups_for_extras(),
+        groups_for_modules: groups_for_modules(),
       ],
 
       # Hex
@@ -45,7 +47,70 @@ defmodule Legendary.Core.MixProject do
   end
 
   defp extras do
-    Path.wildcard("guides/**/*.md")
+    [
+      "guides/overview.md",
+      "guides/tutorial.md",
+      # "guides/tutorial.md": [filename: "tutorial", title: "Tutorial"],
+      "guides/features/admin.md",
+      "guides/features/auth.md",
+      "guides/features/background-jobs.md",
+      "guides/features/content-management.md",
+      "guides/features/devops-templates.md",
+      "guides/features/fluid-email-templates.md",
+      "guides/features/i18n.md",
+      "guides/features/tasks-and-scripts.md",
+    ]
+  end
+
+  defp groups_for_extras do
+    [
+      Guides: ~r{guides/[^\.]+.md},
+    ]
+  end
+
+  defp groups_for_modules do
+    [
+      "Auth": [
+        Legendary.Auth,
+        Legendary.AuthWeb,
+        ~r{Legendary\.Auth(Web)?\..+},
+        Legendary.CoreWeb.Router.PowExtensionRouter
+      ],
+      "Email": [
+        Legendary.CoreEmail,
+        Legendary.CoreMailer,
+        Legendary.CoreWeb.EmailHelpers,
+        Legendary.CoreWeb.CoreEmailView,
+      ],
+      "Internationalization": [
+        Legendary.I18n
+      ],
+      "Mix Tasks": [
+        Legendary.Mix,
+      ],
+      "View Helpers": [
+        Legendary.CoreWeb.ErrorHelpers,
+        Legendary.CoreWeb.Helpers,
+      ],
+      "Core Other": [
+        Legendary.Core,
+        Legendary.Core.MapUtils,
+        Legendary.Core.Repo,
+        Legendary.Core.SharedDBConnectionPool,
+        Mix.Legendary,
+      ],
+      "Web Other": [
+        Legendary.CoreWeb,
+        Legendary.CoreWeb.Endpoint,
+        Legendary.CoreWeb.ErrorView,
+        Legendary.CoreWeb.Gettext,
+        Legendary.CoreWeb.LayoutView,
+        Legendary.CoreWeb.Router,
+        Legendary.CoreWeb.Router.Helpers,
+        Legendary.CoreWeb.Telemetry,
+        Legendary.CoreWeb.UserSocket,
+      ]
+    ]
   end
 
   # Configuration for the OTP application.