Documentation "Quick Start with Igniter" needs tweaks

[jshprentz]

Code of Conduct

• I agree to follow this project's Code of Conduct

AI Policy

• I agree to follow this project's AI Policy, or I agree that AI was not used while creating this issue.

Versions

• Elixir 1.19.5-otp-28
• Erlang 28.4.1
• igniter_new 0.5.33
• bb 0.15.1

Operating system

Ubuntu 24.04.4 LTS running in 5.15.153.1-microsoft-standard-WSL2+

Current Behaviour

Quick Start with Igniter states: The fastest way to get started is with Igniter: mix igniter.install bb. Running that command in an empty directory gives this error message:

** (Mix) The task "igniter.install" could not be found. Did you mean "escript.uninstall"?
Note no mix.exs was found in the current directory

After installing igniter_new-0.5.33, the same command gives this error message:

checking for igniter in project ✔
Updating project's igniter dependency ✔
Not in a mix project. No `mix.exs` file was found.

Did you mean `mix igniter.new`?

After reading some igniter documentation, I had success with the igniter.new command, which created an Elixir project containing the MyRobot.Application and MyRobot.Robot modules.

joel@Joels-Dell-XPS-8940:~/projects/beambots$ mix igniter.new my_robot --install bb
* creating README.md
* creating .formatter.exs
* creating .gitignore
* creating mix.exs
* creating lib
* creating lib/my_robot.ex
* creating test
* creating test/test_helper.exs
* creating test/my_robot_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd my_robot
    mix test

Run "mix help" for more commands.
Fetching and compiling dependencies ✔
installing igniter ✔
Updating project's igniter dependency ✔
compiling igniter ✔
setting up igniter ✔
fetching deps ✔
compiling bb ✔
`bb.install` ✔

The following installer was found and executed: `bb.install`:

Update: .formatter.exs

1 1   |# Used by "mix format"
2 2   |[
3   - |  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
  3 + |  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
  4 + |  import_deps: [:bb]
4 5   |]
5 6   |


Create: lib/my_robot/application.ex

1  |defmodule MyRobot.Application do
2  |  @moduledoc false
3  |
4  |  use Application
5  |
6  |  @impl true
7  |  def start(_type, _args) do
8  |    children = [{MyRobot.Robot, []}]
9  |
10 |    opts = [strategy: :one_for_one, name: MyRobot.Supervisor]
11 |    Supervisor.start_link(children, opts)
12 |  end
13 |end
14 |


Create: lib/my_robot/robot.ex

1  |defmodule MyRobot.Robot do
2  |  use BB
3  |
4  |  commands do
5  |    command :arm do
6  |      handler(BB.Command.Arm)
7  |      allowed_states([:disarmed])
8  |    end
9  |
10 |    command :disarm do
11 |      handler(BB.Command.Disarm)
12 |      allowed_states([:idle])
13 |    end
14 |  end
15 |
16 |  topology do
17 |    link :base_link do
18 |    end
19 |  end
20 |end
21 |


Update: mix.exs

     ...|
15 15   |  def application do
16 16   |    [
17    - |      extra_applications: [:logger]
   17 + |      extra_applications: [:logger],
   18 + |      mod: {MyRobot.Application, []}
18 19   |    ]
19 20   |  end
     ...|


Proceed with changes? [Y/n] Y
Initializing local git repository, staging all files, and committing ⠂fatal: not a git repository (or any of the parent directories): .git
hint: Using 'master' as the name for the initial branch. This default branch name
hint: is subject to change. To configure the initial branch name to use in all
hint: of your new repositories, which will suppress this warning, call:
hint:
hint:   git config --global init.defaultBranch <name>
hint:
hint: Names commonly chosen instead of 'master' are 'main', 'trunk' and
hint: 'development'. The just-created branch can be renamed via this command:
hint:
hint:   git branch -m <name>
Initializing local git repository, staging all files, and committing ✔

Reproduction

1. Create and change to a new directory.

joel@Joels-Dell-XPS-8940:~/projects$ mkdir beambots
joel@Joels-Dell-XPS-8940:~/projects$ cd beambots

2. Run the command from Quick Start with Igniter.

joel@Joels-Dell-XPS-8940:~/projects/beambots$ mix igniter.install bb

3. Install igniter.

joel@Joels-Dell-XPS-8940:~/projects/beambots$ mix archive.install hex igniter_new

4. Repeat the command from Quick Start with Igniter.

joel@Joels-Dell-XPS-8940:~/projects/beambots$ mix igniter.install bb

5. Use the igniter.new command instead of igniter.install.

joel@Joels-Dell-XPS-8940:~/projects/beambots$ mix igniter.new my_robot --install bb

Expected Behaviour

I expected mix igniter.install bb to create a {YourApp}.Robot module with arm/disarm commands and a base link, add it to my supervision tree, and configure the formatter.

As written, Quick Start with Igniter makes two assumptions that were not true in my situation:

1. Igniter was installed.
2. The command mix igniter.install bb was run within an existing Elixir project.

I recommend:

1. List Igniter as a prerequisite for the quick start.
2. State that the mix igniter.install bb must be run in the {YourApp} Elixir project directory.
3. Offer the command I used, mix igniter.new my_robot --install bb, as an alternative, since some users will follow the tutorial without an existing Elixir project.

[jimsynz]

Thanks for the report @jshprentz. I've updated the docs to match and pushed an update to hexdocs.