beter documention

2024-05-15 15:42:39 +00:00 · 2021-12-17 11:56:46 +13:00 · 2021-12-17 11:56:46 +13:00 · 9fe7b313a1
parent 36b74c5171
commit 9fe7b313a1
9 changed files with 90 additions and 77 deletions
--- a/.github/workflows/bonfire.yaml
+++ b/.github/workflows/bonfire.yaml
@ -156,7 +156,7 @@ jobs:
    - name: Set up database
      run: mix ecto.setup
    - name: Generate docs
-      run: mix docs
+      run: make doc
    - name: Deploy docs
      uses: peaceiris/actions-gh-pages@v3
      with:
--- a/3
+++ b/3
@ -102,6 +102,9 @@ else
 	iex -S mix phx.server
 endif

+doc: ## Generate docs from code & readmes
+	@make --no-print-directory cmd cmd="mix docs"
+
 recompile: ## Force the app to recompile
 	@make --no-print-directory cmd cmd="mix compile --force"

--- a/README.md
+++ b/README.md
@ -1,4 +1,5 @@
-## Bonfire 
+# Bonfire 
+
 [Bonfire](https://bonfirenetworks.org/) - a place your community is happy to call home.

 Self-host your online community and shape your experience at the most granular level: add and remove features, change behaviours and appearance, tune, swap or turn off algorithms. You are in total control.
@ -8,12 +9,12 @@ Empower your community with tools to perform social, economic and political acti

 ### Flavours
 This repo includes configurations to run two main [flavours of Bonfire](https://bonfirenetworks.org/use-bonfire/) you can choose from:
-* [Classic](flavours/classic) for basic social networking
-* [Cooperation](flavours/cooperation) with a bunch more extensions and features 
+* [Classic](https://github.com/bonfire-networks/bonfire-app/tree/main/flavours/classic) for basic social networking
+* [Cooperation](https://github.com/bonfire-networks/bonfire-app/tree/main/flavours/cooperation) with a bunch more extensions and features 

 As well as app flavours being built by others, including: 
-* [Haha Academy](flavours/haha) by haha.academy 
-* [Reflow](flavours/reflow) by reflowproject.eu and dyne.org
+* [Haha Academy](https://github.com/bonfire-networks/bonfire-app/tree/main/flavours/haha) by haha.academy 
+* [Reflow](https://github.com/bonfire-networks/bonfire-app/tree/main/flavours/reflow) by reflowproject.eu and dyne.org


 ## Documentation
--- a/flavours/classic/README.md
+++ b/flavours/classic/README.md
@ -1,16 +1,16 @@
-## Bonfire 
+# Bonfire Classic

 This app is part of the [Bonfire](https://bonfirenetworks.org/) ecosystem and bundles the following extensions:

- [Bonfire:Common](https://github.com/bonfire-networks/bonfire_common) - common utils
- [Bonfire:Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
- [Bonfire:Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
- [Bonfire:UI:Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
- [Bonfire:Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
- [Bonfire:Federate:ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
- [Bonfire:Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire:Classify
- [Bonfire:Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
- [Bonfire:Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places
+- [Bonfire.Common](https://github.com/bonfire-networks/bonfire_common) - common utils
+- [Bonfire.Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
+- [Bonfire.Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
+- [Bonfire.UI.Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
+- [Bonfire.Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
+- [Bonfire.Federate.ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
+- [Bonfire.Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire.Classify
+- [Bonfire.Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
+- [Bonfire.Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places


 ## More information
--- a/flavours/cooperation/README.md
+++ b/flavours/cooperation/README.md
@ -1,24 +1,24 @@
-## Bonfire Cooperation 
+# Bonfire Cooperation 

 This app is a flavour of [Bonfire](https://bonfirenetworks.org/) and bundles the following extensions:

- [Bonfire:Common](https://github.com/bonfire-networks/bonfire_common) - common utils
- [Bonfire:Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
- [Bonfire:Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
- [Bonfire:UI:Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
- [Bonfire:Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
- [Bonfire:Federate:ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
- [Bonfire:Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire:Classify
- [Bonfire:Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
- [Bonfire:Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places
- [Bonfire:Quantify](https://github.com/bonfire-ecosystem/bonfire_quantify) - units & measures
- [Bonfire:ValueFlows](https://github.com/bonfire-ecosystem/bonfire_valueflows) - economic activities with ValueFlows
- [Bonfire:ValueFlows:Observe](https://github.com/bonfire-ecosystem/bonfire_valueflows_observe) - observation of economic resources
- [Bonfire:API:GraphQL](https://github.com/bonfire-ecosystem/bonfire_api_graphql) - a GraphQL client API
- [Bonfire:UI:ValueFlows](https://github.com/bonfire-networks/bonfire_ui_valueflows) - reusable frontend components for economic activities 
- [Bonfire:UI:Coordination](https://github.com/bonfire-networks/bonfire_ui_valueflows) - basic coordination UI for projects and communities
- [Bonfire:Kanban](https://github.com/bonfire-networks/bonfire_breadpub) - coordination tools with drag-and-drop card UI
- [Bonfire:Breadpub](https://github.com/bonfire-networks/bonfire_breadpub) - needs & offers for mutual aid
+- [Bonfire.Common](https://github.com/bonfire-networks/bonfire_common) - common utils
+- [Bonfire.Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
+- [Bonfire.Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
+- [Bonfire.UI.Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
+- [Bonfire.Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
+- [Bonfire.Federate.ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
+- [Bonfire.Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire.Classify
+- [Bonfire.Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
+- [Bonfire.Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places
+- [Bonfire.Quantify](https://github.com/bonfire-ecosystem/bonfire_quantify) - units & measures
+- [Bonfire.ValueFlows](https://github.com/bonfire-ecosystem/bonfire_valueflows) - economic activities with ValueFlows
+- [Bonfire.ValueFlows.Observe](https://github.com/bonfire-ecosystem/bonfire_valueflows_observe) - observation of economic resources
+- [Bonfire.API.GraphQL](https://github.com/bonfire-ecosystem/bonfire_api_graphql) - a GraphQL client API
+- [Bonfire.UI.ValueFlows](https://github.com/bonfire-networks/bonfire_ui_valueflows) - reusable frontend components for economic activities 
+- [Bonfire.UI.Coordination](https://github.com/bonfire-networks/bonfire_ui_valueflows) - basic coordination UI for projects and communities
+- [Bonfire.Kanban](https://github.com/bonfire-networks/bonfire_breadpub) - coordination tools with drag-and-drop card UI
+- [Bonfire.Breadpub](https://github.com/bonfire-networks/bonfire_breadpub) - needs & offers for mutual aid


 ## More information
--- a/flavours/haha/README.md
+++ b/flavours/haha/README.md
@ -1,16 +1,16 @@
-## Haha Academy powered by Bonfire 
+# Haha Academy

 This app is part of the [Bonfire](https://bonfirenetworks.org/) ecosystem and bundles the following extensions:

- [Bonfire:Common](https://github.com/bonfire-networks/bonfire_common) - common utils
- [Bonfire:Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
- [Bonfire:Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
- [Bonfire:UI:Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
- [Bonfire:Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
- [Bonfire:Federate:ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
- [Bonfire:Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire:Classify
- [Bonfire:Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
- [Bonfire:Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places
+- [Bonfire.Common](https://github.com/bonfire-networks/bonfire_common) - common utils
+- [Bonfire.Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
+- [Bonfire.Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
+- [Bonfire.UI.Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
+- [Bonfire.Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
+- [Bonfire.Federate.ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
+- [Bonfire.Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire.Classify
+- [Bonfire.Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
+- [Bonfire.Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places


 ## More information
--- a/flavours/reflow/README.md
+++ b/flavours/reflow/README.md
@ -1,22 +1,22 @@
-## Reflow, powered by Bonfire + ValueFlows
+# Reflow

 This app is part of the [Bonfire](https://bonfirenetworks.org/) and [ValueFlows](http://valueflo.ws/) ecosystems and bundles the following extensions:

- [Bonfire:Common](https://github.com/bonfire-networks/bonfire_common) - common utils
- [Bonfire:Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
- [Bonfire:Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
- [Bonfire:UI:Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
- [Bonfire:Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
- [Bonfire:Federate:ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
- [Bonfire:Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire:Classify
- [Bonfire:Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
- [Bonfire:Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places
- [Bonfire:Quantify](https://github.com/bonfire-ecosystem/bonfire_quantify) - units & measures
- [Bonfire:ValueFlows](https://github.com/bonfire-ecosystem/bonfire_valueflows) - economic activities with ValueFlows
- [Bonfire:ValueFlows:Observe](https://github.com/bonfire-ecosystem/bonfire_valueflows_observe) - observation of economic resources
- [Bonfire:API:GraphQL](https://github.com/bonfire-ecosystem/bonfire_api_graphql) - a GraphQL client API
- [Bonfire:UI:ValueFlows](https://github.com/bonfire-networks/bonfire_ui_valueflows) - reusable frontend components for economic activities 
- [Bonfire:UI:Reflow](https://github.com/bonfire-networks/bonfire_ui_reflow) - frontend for the Reflow project
+- [Bonfire.Common](https://github.com/bonfire-networks/bonfire_common) - common utils
+- [Bonfire.Me](https://github.com/bonfire-networks/bonfire_me) - accounts, user profiles...
+- [Bonfire.Social](https://github.com/bonfire-networks/bonfire_social) - feeds, activities, posts, boosting, flagging, etc...
+- [Bonfire.UI.Social](https://github.com/bonfire-ecosystem/bonfire_ui_social) - interface for basic social activities 
+- [Bonfire.Boundaries](https://github.com/bonfire-networks/bonfire_boundaries) - define circles and associated privacy or permissions
+- [Bonfire.Federate.ActivityPub](https://github.com/bonfire-networks/bonfire_federate_activitypub) - federates activities with ActivityPub to participate in the fediverse
+- [Bonfire.Tag](https://github.com/bonfire-ecosystem/bonfire_tag) - @ mentions, hashtags, and tagging using topics/categories from Bonfire.Classify
+- [Bonfire.Classify](https://github.com/bonfire-ecosystem/bonfire_classify) - categories & classifications in taxonomies
+- [Bonfire.Geolocate](https://github.com/bonfire-ecosystem/bonfire_geolocate) - places
+- [Bonfire.Quantify](https://github.com/bonfire-ecosystem/bonfire_quantify) - units & measures
+- [Bonfire.ValueFlows](https://github.com/bonfire-ecosystem/bonfire_valueflows) - economic activities with ValueFlows
+- [Bonfire.ValueFlows.Observe](https://github.com/bonfire-ecosystem/bonfire_valueflows_observe) - observation of economic resources
+- [Bonfire.API.GraphQL](https://github.com/bonfire-ecosystem/bonfire_api_graphql) - a GraphQL client API
+- [Bonfire.UI.ValueFlows](https://github.com/bonfire-networks/bonfire_ui_valueflows) - reusable frontend components for economic activities 
+- [Bonfire.UI.Reflow](https://github.com/bonfire-networks/bonfire_ui_reflow) - frontend for the Reflow project


 ## More information
--- a/lib/application.ex
+++ b/lib/application.ex
@ -1,5 +1,4 @@
 defmodule Bonfire.Application do
-  @moduledoc false

  @sup_name Bonfire.Supervisor
  @name Mix.Project.config()[:name]
--- a/mix.exs
+++ b/mix.exs
@ -2,10 +2,20 @@ Code.eval_file("mess.exs")
 defmodule Bonfire.MixProject do
  use Mix.Project

-  @config [
+  @config [ # TODO: put these in ENV or an external writeable config file similar to deps.*
      version: "0.1.0-beta.74", # note that the flavour will automatically be added where the dash appears
      elixir: "~> 1.12",
      default_flavour: "classic",
+      logo: "assets/static/images/bonfire-icon.png",
+      docs: [
+        "README.md",
+        "docs/HACKING.md",
+        "docs/DEPLOY.md",
+        "docs/ARCHITECTURE.md",
+        # "docs/DEPENDENCIES.md",
+        "docs/GRAPHQL.md",
+        "docs/MRF.md"
+      ],
      deps_prefixes: [
        docs: ["bonfire_"],
        test: ["bonfire_", "pointers", "paginator"],
@ -31,19 +41,13 @@ defmodule Bonfire.MixProject do
      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"
-        ],
+        logo: @config[:logo],
        output: "docs/exdoc",
-        source_beam: docs_paths()
+        # extra pages to include
+        extras: readme_paths(),
+        # extra apps to include
+        source_beam: docs_paths(),
+        deps: doc_deps()
      ],
    ]

@ -179,11 +183,17 @@ defmodule Bonfire.MixProject do

  def docs_paths() do
    build = Mix.Project.build_path()
-    docs_apps()
+    ([:bonfire] ++ deps(:docs))
    |> 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"])
+  defp docs_path(app, build), do: Path.join([build, "lib", dep_name(app), "ebin"])
+
+  def readme_paths(), do: (@config[:docs] ++ Enum.map(Path.wildcard("flavours/*/README.md"), &flavour_readme/1) ++ Enum.map(deps(:docs), &readme_path/1))
+  defp readme_path(dep), do: {dep_paths(dep, "README.md") |> List.first |> String.to_atom, [filename: dep_name(dep)]}
+  def flavour_readme(path), do: {path |> String.to_atom, [filename: path |> String.split("/") |> Enum.at(1)]}
+
+  defp doc_deps(), do: deps(:docs) |> Enum.map(&doc_dep/1) #[plug: "https://myserver/plug/"]
+  defp doc_dep(dep), do: {elem(dep, 0), "./"}

  # Specifies which paths to include when running tests
  defp test_paths(), do: ["test" | Enum.flat_map(deps(:test), &dep_paths(&1, "test"))]