From 91f960cc9413e4b7a5131b2988310a80dc5df9b4 Mon Sep 17 00:00:00 2001 From: Robert Prehn <3952444+prehnRA@users.noreply.github.com> Date: Fri, 2 Apr 2021 17:49:58 -0500 Subject: [PATCH] chore: Create initial documentation shell --- apps/core/guides/features/admin.md | 1 + apps/core/guides/features/auth.md | 1 + apps/core/guides/features/background-jobs.md | 1 + .../guides/features/content-management.md | 1 + apps/core/guides/features/devops-templates.md | 1 + .../guides/features/fluid-email-templates.md | 1 + apps/core/guides/features/i18n.md | 1 + .../core/guides/features/tasks-and-scripts.md | 1 + apps/core/guides/overview.md | 29 +++++--- apps/core/guides/tutorial.md | 1 + apps/core/lib/core_web/views/helpers.ex | 2 +- apps/core/mix.exs | 71 ++++++++++++++++++- 12 files changed, 98 insertions(+), 13 deletions(-) create mode 100644 apps/core/guides/features/admin.md create mode 100644 apps/core/guides/features/auth.md create mode 100644 apps/core/guides/features/background-jobs.md create mode 100644 apps/core/guides/features/content-management.md create mode 100644 apps/core/guides/features/devops-templates.md create mode 100644 apps/core/guides/features/fluid-email-templates.md create mode 100644 apps/core/guides/features/i18n.md create mode 100644 apps/core/guides/features/tasks-and-scripts.md create mode 100644 apps/core/guides/tutorial.md diff --git a/apps/core/guides/features/admin.md b/apps/core/guides/features/admin.md new file mode 100644 index 00000000..aad94154 --- /dev/null +++ b/apps/core/guides/features/admin.md @@ -0,0 +1 @@ +# Admin diff --git a/apps/core/guides/features/auth.md b/apps/core/guides/features/auth.md new file mode 100644 index 00000000..e97b0679 --- /dev/null +++ b/apps/core/guides/features/auth.md @@ -0,0 +1 @@ +# Authentication and Authorization diff --git a/apps/core/guides/features/background-jobs.md b/apps/core/guides/features/background-jobs.md new file mode 100644 index 00000000..e6291265 --- /dev/null +++ b/apps/core/guides/features/background-jobs.md @@ -0,0 +1 @@ +# Background Jobs diff --git a/apps/core/guides/features/content-management.md b/apps/core/guides/features/content-management.md new file mode 100644 index 00000000..1a420e8e --- /dev/null +++ b/apps/core/guides/features/content-management.md @@ -0,0 +1 @@ +# Content Management diff --git a/apps/core/guides/features/devops-templates.md b/apps/core/guides/features/devops-templates.md new file mode 100644 index 00000000..3e40f583 --- /dev/null +++ b/apps/core/guides/features/devops-templates.md @@ -0,0 +1 @@ +# DevOps Templates diff --git a/apps/core/guides/features/fluid-email-templates.md b/apps/core/guides/features/fluid-email-templates.md new file mode 100644 index 00000000..59585663 --- /dev/null +++ b/apps/core/guides/features/fluid-email-templates.md @@ -0,0 +1 @@ +# Fluid Email Templates diff --git a/apps/core/guides/features/i18n.md b/apps/core/guides/features/i18n.md new file mode 100644 index 00000000..05b5b619 --- /dev/null +++ b/apps/core/guides/features/i18n.md @@ -0,0 +1 @@ +# I18n diff --git a/apps/core/guides/features/tasks-and-scripts.md b/apps/core/guides/features/tasks-and-scripts.md new file mode 100644 index 00000000..adde2d85 --- /dev/null +++ b/apps/core/guides/features/tasks-and-scripts.md @@ -0,0 +1 @@ +# Tasks and Scripts diff --git a/apps/core/guides/overview.md b/apps/core/guides/overview.md index 832d9522..0ff8f53b 100644 --- a/apps/core/guides/overview.md +++ b/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 +``` + 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 -changing those as much as possible, because doing so will make it more difficult -to upgrade Legendary to newer versions. However, they are available to you if -you find that there are no other ways to accomplish the changes you want to -accomplish. If you find yourself adding functionality to admin, content, or core +are part of the framework-- apps/admin, apps/content, apps/core. We encourage you +to avoid changing those as much as possible, because doing so will make it more +difficult to upgrade Legendary to newer versions. However, they are available to +you if you find that there are no other ways to accomplish the changes that you want. +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 -token should be a [personal access token](/-/profile/personal_access_tokens) with +need to configure a [CI variable](https://docs.gitlab.com/ee/ci/variables/) named +`GITLAB_TOKEN`. This token should be a +[personal access token](https://gitlab.com/-/profile/personal_access_tokens) with `read_repository, write_repository` permissions. diff --git a/apps/core/guides/tutorial.md b/apps/core/guides/tutorial.md new file mode 100644 index 00000000..4f50eccc --- /dev/null +++ b/apps/core/guides/tutorial.md @@ -0,0 +1 @@ +# Tutorial diff --git a/apps/core/lib/core_web/views/helpers.ex b/apps/core/lib/core_web/views/helpers.ex index 4af16e83..0bfa73b1 100644 --- a/apps/core/lib/core_web/views/helpers.ex +++ b/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 diff --git a/apps/core/mix.exs b/apps/core/mix.exs index 828e3789..e3a23f62 100644 --- a/apps/core/mix.exs +++ b/apps/core/mix.exs @@ -26,8 +26,10 @@ defmodule Legendary.Core.MixProject do homepage_url: "https://legendaryframework.org/", docs: [ main: "overview", - extra_section: "GUIDES", - extras: extras() + extra_section: "Getting Started", + 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.