generate docs

.github/workflows/bonfire.yaml

@@ -13,6 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     container: elixir:alpine
     env:
+      FLAVOUR=cooperation
       POSTGRES_HOST: postgres
       POSTGRES_PASSWORD: postgres
       CI: true
@@ -74,12 +75,19 @@ jobs:
       run: mix bonfire.deps.update
     - name: Fetch any differences in dep version
       run: mix deps.get
-    - name: Clean-build Bonfire extensions
+    - name: Clean-build Bonfire data extensions
       run: mix bonfire.deps.clean
     - name: Compile deps & app
       run: MIX_ENV=test mix
     - name: Set up database
       run: MIX_ENV=test mix ecto.setup
+    - name: Generate docs
+      run: MIX_ENV=test mix docs
+    - name: Deploy docs
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/exdoc
     - name: Run tests
       run: mix test
     - name: Check that database migrations can rollback

.gitignore

@@ -75,6 +75,7 @@ deploy
 priv/localisation/*
 .tailwindcss/touch/
 .local/state/
+docs/exdoc
 
 # we use pnpm, so ignore others
 assets/package-lock.json

lib/web/graphql/schema.ex

@@ -1,7 +1,7 @@
 if Bonfire.Common.Utils.module_enabled?(Bonfire.GraphQL) and Bonfire.Common.Utils.module_enabled?(ValueFlows.Schema) do
 # SPDX-License-Identifier: AGPL-3.0-only
 defmodule Bonfire.GraphQL.Schema do
-  @moduledoc "Root GraphQL Schema"
+  @moduledoc "Root GraphQL Schema. Only active if the `Bonfire.GraphQL` extension is present. "
   use Absinthe.Schema
   @schema_provider Absinthe.Schema.PersistentTerm
   # @pipeline_modifier Bonfire.GraphQL.SchemaPipelines

mix.exs

@@ -6,8 +6,11 @@ defmodule Bonfire.MixProject do
       version: "0.1.0-beta.39", # note that the flavour will automatically be added where the dash appears
       elixir: "~> 1.12",
       default_flavour: "classic",
-      test_deps_prefixes: ["bonfire_", "pointers", "paginator"],
-      data_deps_prefixes: ["bonfire_data_", "pointers", "bonfire_tag", "bonfire_classify", "bonfire_geolocate"]
+      deps_prefixes: [
+        docs: ["bonfire_"],
+        test: ["bonfire_", "pointers", "paginator"],
+        data: ["bonfire_data_", "pointers", "bonfire_tag", "bonfire_classify", "bonfire_geolocate"]
+      ]
     ]
 
   def project do
@@ -24,7 +27,24 @@ defmodule Bonfire.MixProject do
       config_path: config_path("config.exs"),
       releases: [
         bonfire: [runtime_config_path: config_path("runtime.exs")],
-      ]
+      ],
+      docs: [
+        # The first page to display from the docs
+        main: "readme",
+        logo: "assets/static/images/bonfire-icon.png",
+        # extra pages to include
+        extras: [
+          "README.md",
+          "docs/HACKING.md",
+          "docs/DEPLOY.md",
+          "docs/ARCHITECTURE.md",
+          # "docs/DEPENDENCIES.md",
+          "docs/GRAPHQL.md",
+          "docs/MRF.md"
+        ],
+        output: "docs/exdoc",
+        source_beam: docs_paths()
+      ],
     ]
 
   end
@@ -74,6 +94,7 @@ defmodule Bonfire.MixProject do
       {:phoenix_live_reload, "~> 1.3", only: :dev},
       {:exsync, "~> 0.2", only: :dev},
       {:mix_unused, "~> 0.3.0", only: :dev},
+      {:ex_doc, "~> 0.24", only: :dev, runtime: false},
 
       # tests
       {:floki, ">= 0.0.0", only: [:dev, :test]},
@@ -152,6 +173,16 @@ defmodule Bonfire.MixProject do
     |> Enum.map(&dep_name/1)
   end
 
+  # Specifies which paths to include in docs
+
+  def docs_paths() do
+    build = Mix.Project.build_path()
+    docs_apps()
+    |> Enum.map(&docs_path(&1, build))
+  end
+  defp docs_apps(), do: [:bonfire] ++ deps(:docs)
+  defp docs_path(app, build \\ Mix.Project.build_path()), do: Path.join([build, "lib", dep_name(app), "ebin"])
+
   # Specifies which paths to include when running tests
   defp test_paths(), do: ["test" | Enum.flat_map(deps(:test), &dep_paths(&1, "test"))]
 
@@ -159,12 +190,10 @@ defmodule Bonfire.MixProject do
   defp elixirc_paths(:test), do: ["lib", "test/support" | Enum.flat_map(deps(:test), &dep_paths(&1, "test/support"))]
   defp elixirc_paths(env), do: ["lib"] ++ catalogues(env)
 
-  defp include_dep?(:test, dep), do: String.starts_with?(dep_name(dep), @config[:test_deps_prefixes])
-
-  defp include_dep?(:data, dep), do: String.starts_with?(dep_name(dep), @config[:data_deps_prefixes])
-
   defp include_dep?(:update, dep) when is_tuple(dep), do: unpinned_git_dep?(dep)
 
+  defp include_dep?(type, dep), do: String.starts_with?(dep_name(dep), @config[:deps_prefixes][type])
+
   defp unpinned_git_dep?(dep) do
     spec = elem(dep, 1)
     is_list(spec) && spec[:git] && !spec[:commit]

mix.lock

@@ -62,6 +62,7 @@
   "email_checker": {:hex, :email_checker, "0.2.1", "7fe36fc7cfbbf02b37040fcafbd6a27aca56ab344bcf8138a71a9549a57b4117", [:mix], [{:socket, "~> 0.3.1", [hex: :socket, repo: "hexpm", optional: true]}], "hexpm", "4abb60a4bf67782d4cec5d41417e30dc54ff64e2fce356409914e809688403ac"},
   "emote": {:git, "https://github.com/bonfire-networks/emote", "088e33d61b22319c1a59b97a88ad3864fff88148", []},
   "eternal": {:hex, :eternal, "1.2.2", "d1641c86368de99375b98d183042dd6c2b234262b8d08dfd72b9eeaafc2a1abd", [:mix], [], "hexpm", "2c9fe32b9c3726703ba5e1d43a1d255a4f3f2d8f8f9bc19f094c7cb1a7a9e782"},
+  "ex_doc": {:hex, :ex_doc, "0.25.5", "ac3c5425a80b4b7c4dfecdf51fa9c23a44877124dd8ca34ee45ff608b1c6deb9", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "688cfa538cdc146bc4291607764a7f1fcfa4cce8009ecd62de03b27197528350"},
   "ex_machina": {:hex, :ex_machina, "2.7.0", "b792cc3127fd0680fecdb6299235b4727a4944a09ff0fa904cc639272cd92dc7", [:mix], [{:ecto, "~> 2.2 or ~> 3.0", [hex: :ecto, repo: "hexpm", optional: true]}, {:ecto_sql, "~> 3.0", [hex: :ecto_sql, repo: "hexpm", optional: true]}], "hexpm", "419aa7a39bde11894c87a615c4ecaa52d8f107bbdd81d810465186f783245bf8"},
   "ex_maybe": {:hex, :ex_maybe, "1.1.1", "95c0188191b43bd278e876ae4f0a688922e3ca016a9efd97ee7a0b741a61b899", [:mix], [], "hexpm", "1af8c78c915c7f119a513b300a1702fc5cc9fed42d54fd85995265e4c4b763d2"},
   "ex_unit_notifier": {:hex, :ex_unit_notifier, "1.2.0", "73ced2ecee0f2da0705e372c21ce61e4e5d927ddb797f73928e52818b9cc1754", [:mix], [], "hexpm", "f38044c9d50de68ad7f0aec4d781a10d9f1c92c62b36bf0227ec0aaa96aee332"},
@@ -94,6 +95,7 @@
   "livebook": {:git, "https://github.com/mayel/livebook", "9f9f54d224e25a4cb94e19a2b6a3f49557ee07a7", [branch: "fork"]},
   "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
   "makeup_elixir": {:hex, :makeup_elixir, "0.15.1", "b5888c880d17d1cc3e598f05cdb5b5a91b7b17ac4eaf5f297cb697663a1094dd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "db68c173234b07ab2a07f645a5acdc117b9f99d69ebf521821d89690ae6c6ec8"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
   "mappable": {:hex, :mappable, "0.2.4", "3038564db78bbde442100d9252aac484be746612bc74b333fbeaeffec8087efa", [:mix], [], "hexpm", "188d9291ca5eec10af61420b6738ef69244b7d7ec6dc98f7f4aa7a4e21f1a8b5"},
   "matrix_reloaded": {:hex, :matrix_reloaded, "2.2.1", "9786e97c20535e902dbe586b704ede6c00a6854609715fb161645df9cd99ca55", [:mix], [{:ex_maybe, "~> 1.0", [hex: :ex_maybe, repo: "hexpm", optional: false]}, {:result, "~> 1.3.0", [hex: :result, repo: "hexpm", optional: false]}], "hexpm", "d5e3c9b6dfb6b1f5c35439674177f421a8eec9a1ac5d40f2d1115c5cbb116fc3"},
   "meck": {:hex, :meck, "0.9.2", "85ccbab053f1db86c7ca240e9fc718170ee5bda03810a6292b5306bf31bae5f5", [:rebar3], [], "hexpm", "81344f561357dc40a8344afa53767c32669153355b626ea9fcbc8da6b3045826"},