Add docs to Mix tasks #41

joustava · 2025-02-05T19:20:33Z

Made changes to the Mix task implementations so that

mix help will now list the available atomvm.* task
mix doc will generate ex docs

Am not sure how to word the moduledoc for the check task though, feedback welcome.

Closes #40

lib/mix/tasks/esp32_flash.ex

lib/mix/tasks/pico_flash.ex

lib/mix/tasks/esp32_flash.ex

petermm · 2025-02-06T08:40:01Z

Looking good, I would back out the readme changes - pending other PR, or wait for it to land and rebase..

And then just the minor nitpicks..

Thanks!

UncleGrumpy · 2025-02-06T22:59:05Z

The check task, if you want to document it verifies that the functions and modules used are either part of the application source (or deps) or supported by AtomVM. This will catch the use of any standard Elixir modules or functions used in the application that are not included in exavmlib.

The packbeam task depends on this one, so users will likely never need to use it directly, but just in case they are wondering what it is doing a short module doc description wouldn’t hurt.

UncleGrumpy · 2025-02-07T16:08:27Z

lib/mix/tasks/packbeam.ex

+  @shortdoc "Bundle the application into an AVM file"
+
+  @moduledoc """
+  Bundle an application into an AVM file that can be flashed to a micro-controller and executed by the AtomVM virtual machine.


Maybe mention running on generic_unix too?
...flashed to a micro-controller and (or directly on a unix host) executed by the AtomVM virtual machine.

UncleGrumpy

Sorry this is turning into a bigger job than you probably anticipated, we all really appreciate your work here ;-). I just found a couple small details. Also if you change your PR description to so say "Closes #40" instead, the issue will automatically be closed when the PR is merged.

UncleGrumpy · 2025-02-07T16:13:59Z

lib/mix/tasks/stm32_flash.ex

+  >
+  > Note. Before running this task, you must flash the AtomVM virtual machine to the target device.
+  >
+  > This tasks depends on a host installation of STM32 tooling, see [](https://www.atomvm.net/doc/main/build-instructions.html#building-for-stm32)


Missing the name for the link here. [STM32 Build Instructions]

Ah, nice catch.

lib/mix/tasks/uf2create.ex

UncleGrumpy

Sorry I didn't catch this little detail sooner;-)

UncleGrumpy · 2025-02-07T18:33:09Z

lib/mix/tasks/packbeam.ex

+  Within your AtomVM mix project run
+
+  `
+  $ mix atomvm.packbeam --start MyProject


The --start module option should only be used to override the :start defined in the :atomvm mix.exs. This would not normally be needed, unless the user had an alternate mode of operation... like a client/server app that normally builds the client, but when building the server uses a different start module.

added. Also made the admonition blocks more prominent where applicable.

UncleGrumpy

Your fixes, brought up another little detail. But this is minor, so feel free to leave things as they are ;-)

lib/mix/tasks/packbeam.ex

UncleGrumpy

This looks fantastic! Just one little typo.

And we need you have you sign off on the commit. Looks like we need a workflow in place to check for that.

This is the very last little detail, I promise! ;-)

UncleGrumpy · 2025-02-09T18:22:24Z

lib/mix/tasks/packbeam.ex

+
+  > #### Info {: .info}
+  >
+  > Normally using this task manually is not required, it is called automatically by `atomvm.esp32.flash`, `atomvm.stm32.flash` nd `atomvm.pico.flash`.


Typo nd -> and ;-)

UncleGrumpy · 2025-02-10T00:00:55Z

To add a signoff to your commit you can use:

git commit --amend --signoff

…or the short option -s to add the sign off.

UncleGrumpy

This looks great! Should be ready to merge. Than you so much for all the effort and putting up with the nit-picking 😁

petermm · 2025-02-13T11:00:40Z

Let's back out mix.lock and it should be good to go.

Adding it at this stage only creates issues, and solves none. (eg is this mix.lock valid on elixir 1.X), will it load outdated ex_doc, once we start using that etc.

Surely we will add mix.lock once it's beneficial, but even then it may be sideloaded in Docs CI - since elixir 1.7-1.19 is theoretically supported, and I foresee a mix.lock conflicting with that, I could just be imagining that, but I'm not gonna investigate.

petermm · 2025-02-15T09:18:10Z

mix.exs

@@ -21,7 +32,8 @@ defmodule ExAtomVM.MixProject do
  # Run "mix help deps" to learn about dependencies.
  defp deps do
    [
-      {:uf2tool,  "1.1.0"}
+      {:uf2tool, "1.1.0"},
+      {:ex_doc, "~> 0.34", only: :dev, runtime: false}


"~> 0.34" -> "~> 0.20"

for maximum compatibility with anybody running old elixir versions..

Good catch!

petermm · 2025-02-15T09:25:12Z

great work @joustava - thank you, and apologies for things not being straightforward...

- mix help will now list the available atomvm task - mix doc will generate ex docs Signed-off-by: Joost Oostdijk <[email protected]>

joustava · 2025-05-08T16:07:10Z

Is this waiting for my input?

UncleGrumpy · 2025-05-08T16:54:41Z

Is this waiting for my input?

No, I believe everything is good on your end. We just need to have @bettio review and handle merging.

petermm reviewed Feb 5, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

petermm reviewed Feb 5, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Show resolved Hide resolved

petermm reviewed Feb 5, 2025

View reviewed changes

lib/mix/tasks/pico_flash.ex Outdated Show resolved Hide resolved

joustava force-pushed the add-help-to-mix-tasks branch from c7339fa to 06751af Compare February 6, 2025 07:22

joustava marked this pull request as draft February 6, 2025 07:24

petermm reviewed Feb 6, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

petermm reviewed Feb 6, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

petermm reviewed Feb 6, 2025

View reviewed changes

lib/mix/tasks/esp32_flash.ex Outdated Show resolved Hide resolved

joustava force-pushed the add-help-to-mix-tasks branch 2 times, most recently from 72daae7 to d2b7dfc Compare February 6, 2025 17:01

joustava marked this pull request as ready for review February 6, 2025 18:11

petermm approved these changes Feb 6, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from d2b7dfc to fb9d347 Compare February 7, 2025 12:28

petermm mentioned this pull request Feb 7, 2025

Use the Config module instead of Mix.Config is deprecated #42

Closed

UncleGrumpy reviewed Feb 7, 2025

View reviewed changes

UncleGrumpy suggested changes Feb 7, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from fb9d347 to f61d985 Compare February 7, 2025 18:12

petermm approved these changes Feb 7, 2025

View reviewed changes

UncleGrumpy suggested changes Feb 7, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from f61d985 to ffaa819 Compare February 7, 2025 19:11

UncleGrumpy approved these changes Feb 7, 2025

View reviewed changes

lib/mix/tasks/packbeam.ex Show resolved Hide resolved

joustava force-pushed the add-help-to-mix-tasks branch from ffaa819 to 84af458 Compare February 9, 2025 08:13

UncleGrumpy suggested changes Feb 9, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from 84af458 to 9da76d0 Compare February 9, 2025 20:44

joustava force-pushed the add-help-to-mix-tasks branch from 9da76d0 to 6c4cc2b Compare February 10, 2025 18:43

UncleGrumpy approved these changes Feb 11, 2025

View reviewed changes

joustava force-pushed the add-help-to-mix-tasks branch from 6c4cc2b to 14ceda8 Compare February 14, 2025 06:51

petermm reviewed Feb 15, 2025

View reviewed changes

Add docs to Mix tasks

3102630

- mix help will now list the available atomvm task - mix doc will generate ex docs Signed-off-by: Joost Oostdijk <[email protected]>

joustava force-pushed the add-help-to-mix-tasks branch from 14ceda8 to 3102630 Compare February 15, 2025 19:56

bettio approved these changes Aug 7, 2025

View reviewed changes

bettio merged commit b9c3a41 into atomvm:main Aug 7, 2025

Add docs to Mix tasks #41

Add docs to Mix tasks #41

Uh oh!

Conversation

joustava commented Feb 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petermm commented Feb 6, 2025

Uh oh!

UncleGrumpy commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

UncleGrumpy left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

UncleGrumpy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

UncleGrumpy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

UncleGrumpy left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

UncleGrumpy commented Feb 10, 2025

Uh oh!

UncleGrumpy left a comment

Choose a reason for hiding this comment

Uh oh!

petermm commented Feb 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

petermm commented Feb 15, 2025

Uh oh!

joustava commented May 8, 2025

Uh oh!

UncleGrumpy commented May 8, 2025

Uh oh!

Uh oh!

joustava commented Feb 5, 2025 •

edited

Loading

UncleGrumpy commented Feb 6, 2025 •

edited

Loading

UncleGrumpy left a comment •

edited

Loading

UncleGrumpy left a comment •

edited

Loading